World of Graphics/WOGRAPH.BIN/509.MANUAL.DOC

Text File | 1992-10-15 | 208KB | 5,317 lines

                     DOCUMENTATION FOR


             VERSION 7.32 (October 15th, 1992)

                             OF





                            P11



               A GRAPHICS PROGRAM WRITTEN BY:

                     RUSSELL D. HOFFMAN
                      P.O. Box 188006
                     CARLSBAD, CA 92009
                       [phone]
                       [phone]
                 America Online:RUSSELL DH
                   CompuServe:70743,1226




     THE AUTHOR ASSUMES NO RESPONSIBILITIES AS TO THE
    APPLICABILITY OF THIS PROGRAM TO YOUR NEEDS OR THE
 ACCURACY OF ITS FUNCTIONS.  PLEASE NOTIFY THE AUTHOR OF
 ANY INACCURACIES FOUND AND OF ANY DESIRED NEW FEATURES.






         CONCEIVED, DESIGNED, WRITTEN AND PRODUCED
   BY RUSSELL D. HOFFMAN IN THE UNITED STATES OF AMERICA.
            PROGRAM COPYRIGHT (c) 1984 to 1992,
   DOCUMENTATION COPYRIGHT (c) 1985 to 1992 by RUSSELL D.
                          HOFFMAN.



               ALL WORLDWIDE RIGHTS RESERVED.

This document is copyrighted.  No portion may be reproduced,
copied, duplicated  or stored in an electronic access system
for retrieval  by persons  other  than  the  rightful  owner
and/or user of this product without prior written permission
of the  author, except  small  portions  may  be  taken  for
purposes of review or training.  This version supersedes all
previous releases  of this  document and  the P11  family of
graphics  products.    This  version  is  SHAREWARE  and  is
dedicated to  the thousands of users who have contributed to
this product over the years, in so many ways.  Thanks to all
of you, past, present,... and future!


Proudly manufactured in the United States of America.

First printing:  Version 3.00.00, October, 1987. (Some prior
limited distribution.  (Program versions 3.20 & 3.21, 3.50 &
3.51)
Second printing: Version 4.80.00, March, 1989.
Third Printing:  Version 6.00.00,  May, 1990.  (Main program
     release was 6.40 (editor) and 6.41 (runtime)
Fourth  "Printing":   Version  7.22.00,   Aug.   4th,   1992
     (Shareware)
Fifth  "Printing":   Version   7.24.00,   Aug.   9th,   1992
     (Shareware)
Sixth  "Printing":   Version  7.26.00,   Aug.   14th,   1992
     (Shareware)
Seventh  "Printing":   Version  7.30.00,   Oct.  9th,   1992
     (Shareware)

This technical  reference and it's accompanying tutorial and
addenda have  been completely  revised and  updated for  use
with the  current version  of P11  and P11RUN.    Additional
addenda to  this document  may be  included  for  subsequent
releases of  P11 and/or  P11RUN.   The manufacturer reserves
the  right   to  make   changes  to   the  programs   and/or
documentation without prior notice or obligation.


Numerous companies  produce products  that are  important to
the satisfactory  use of  this  product.    Throughout  this
manual  these   products  are  mentioned.    Many  of  these
product's names   are  trademarked and  we have attempted to
list the owners of these trademarks below.

     I.B.M., PC, PC/XT, PC/AT, PS/2, and PC-DOS are all
  registered trademarks of International Business Machines
                        Corporation.
  Softgraf is a registered trademark of AutoScribe Corp.,
                       Rockville, MD
    Compaq is a registered trademark of Compaq Computer
                        Corporation.
  Summagraphics is a registered trademark of Summagraphics
                           Corp.
 MS-DOS is a registered trademark of Microsoft Corporation.
  Manager Mouse is a registered trademark of The Numonics
                          Company.
HP Laserjet is a registered trademark of the Hewlett-Packard
                          Company.
  RADIO SHACK and TANDY are registered trademarks of Radio
                        Shack, Inc.
  ATI WONDER CARD and WONDER MOUSE are trademarks of ATI,
                           Canada
  QEMM is a trademark of Quarterdeck Office Systems, Santa
                         Monica, CA
    GRAPHICS MASTER is a registered trademark of TECMAR.

Additional trademarks belong to the companies listed herein.







                     TABLE OF CONTENTS

     COMMANDS AND SYNTAX ................... 1



     Alphabetical Listing Of All Commands

               ACTIVATE ............. 2
               ADD .................. 3
               APPEND ............... 4
               AUTHORITY ............ 5
               BEEP ................. 6
               BLANK ................ 7
               BREAK ................ 8
               BUILD ................ 9
               BUTTON ............... 10
               CALL ................. 11
               CALLM ................ 12
               CIRCLE ............... 13
               CLEAR ................ 14
               CLOCK ................ 15
               CLOSE ................ 16
               CONNECT .............. 17
               CONVERT .............. 18
               CRAWL ................ 19
               CURSOR ............... 20
               DATA ................. 21
               DELETE ............... 22
               DIGITIZER ............ 23
               DISPLAY .............. 24
               DIVIDE ............... 25
               DOT .................. 26
               DRAW ................. 27
               ELIMINATE ............ 28
               ELSE ................. 29
               END .................. 30
               ENDIF ................ 31
               ERROR ................ 32
               EXCHANGE ............. 33
               EXECUTE .............. 34
               FRAME ................ 36
               HEIGHT ............... 37
               HUE .................. 38
               IF ................... 39
               IN ................... 40
               JOYSTICK ............. 41
               JRCOLOR .............. 42
               JUMP ................. 43
               KEY .................. 44
               LENGTH ............... 45
               LINE ................. 46
               LOCATE ............... 47
               LOAD ................. 48
               MARQUE ............... 49
               MEMORY ............... 50
               MOUSE ................ 51
               MOVE ................. 52
               MULTIPLY ............. 53
               NAME ................. 54
               ON ERROR ............. 55
               ON KEY ............... 56
               OPEN ................. 57
               OUT .................. 58
               OVERLAY .............. 59
               PAINT ................ 60
               PASSWORD ............. 61
               PEN .................. 62
               PRINT ................ 63
               QUESTION ............. 64
               READ ................. 65
               RESTORE .............. 66
               RETURN ............... 67
               ROTATE ............... 68
               ROUNDS ............... 69
               RUN .................. 70
               SAVE ................. 71
               SCREEN ............... 72
               SCROLL ............... 73
               SET .................. 74
               SHOW ................. 75
               SOUND ................ 76
               SPRINT ............... 77
               SPRITE ............... 78
               SUBTRACT ............. 79
               TEXT ................. 80
               THEN ................. 81
               WAIT ................. 82
               WIDTH ................ 83
               WRITE ................ 84
               X .................... 85
               ZING ................. 86
               * .................... 87
               " .................... 88
               + .................... 89

     \RUN Information Displays....... 90
     Picture and Font File Formats... 91
     Format for the Auxiliary File... 92
     Format for the Hue File......... 93
     Space Considerations............ 94
     Tips On Making Your Program Faster  95
     Uses of the "escape" key........ 96
     F10-"Instant" commands & DOS functions   97
     Future Enhancements............. 98
     Of Mice and Joysticks and Digitizers     99
     Timing Considerations........... 100
     Converting Images Between Screen Modes   101
     Executing DOS from within the program    102
     About the Author................ 103











                    COMMANDS AND SYNTAX




     Commands in  this language  are based on ENGLISH words.
All commands  have a  backslash in  column one  and then the
command.   You may  have one  or  more  spaces  between  the
backslash  and  the  command  word.    If  the  command  has
parameters these  should follow AT LEAST ONE SPACE after the
command word.
     You may  have multiple  commands on  a single line, but
the first  character of  each command  must be  a backslash.
The \", \+, and \* commands if used must be the last command
on the line.
     \ON KEY  commands, which  allow the user to move around
within the text file, are only checked between lines (except
during \",  \X, \MARQUE,  \SHOW and \RUN).  \ON KEY checking
will not  occur between  lines if  the last  command on  the
previous line is \+ (see that command for more information).
Temporary suspension  of key checking (except for the ESCAPE
key) enhances  the usefulness  of the \ON KEY command and is
explained in more detail in the command description.
     Usually only  the first  1, 2,  3 or  (sometimes)  more
letters are  evaluated when  the program  decides what  word
(command) you  have specified.   Some commands must be coded
exactly as  they appear  in this  manual, particularly \END,
\ELSE, and  \ENDIF.   All commands  must have enough of them
coded to  distinguish them  from all  other commands.  Since
future releases will include additional commands, the use of
abbreviations is NOT AN APPROVED TECHNIQUE.  It is mentioned
here "for documentation purposes only."


     PARAMETERS
     Some commands  can have  a varying number of parameters
following them.   Some may or may not have any parameters at
all.  Most expect commas to separate a series of values.
     Parameters may  be positional or keywords, depending on
the command.  As an example of positional parameters, assume
you have  issued a  command to  draw a  MARQUE (such as they
have on  Broadway) on  the screen.   This program has such a
command.  Here is an example:

          \MARQUE 20,24,40,50

     This will  display a  moving  rectangular  marque  with
opposite corners  at dot 20,24 and dot 40,50.  The syntax of
this command (so far) is \MARQUE #,#,#,#.


     KEYWORDS
     Some commands  have "KEYWORD="  parameters.  \MOUSE and
\SPRITE are  good examples.   A typical \MOUSE command might
look like this:

          \MOUSE LOCATION=180,100 WINDOW=33,53,188,130
          ROUNDS=30

     This will  display a  mouse cursor  at location 180,100
(near the  middle of  the screen), in a window with opposite
corners at 33,53 and 188,130.  It will display for 30 rounds
(see \MOUSE for an explanation of the ROUNDS option).
     Parameters,  whether  positional  or  keyword,  may  be
specified with  numeric literals,  auxboxes,  variables,  or
mathematical expressions.


     MATHEMATICAL EXPRESSIONS
     Let's say  you don't want to say dot 20,24 as the upper
left corner  of the  MARQUE, but  rather, dot (10 + 10),(8 +
16).   This is actually the SAME DOT!  10 plus 10 is twenty,
and 8  plus 16  is twenty-four.  You may use parenthesis and
variables just as you would in high-school algebra.  You can
use operators  for addition, subtraction, multiplication and
division (+,-,/,*)  with or  without using parenthesis.  The
order of  evaluation, as with algebra, is parenthesis first,
then multiplication  and division  equally (left  to right),
and then addition and subtraction equally (left to right.)


     AUXBOXES
     Suppose you  don't want  to specify  an exact place for
the MARQUE,  but rather, you want to use values contained in
your auxboxes.   The \MARQUE command, using auxboxes, (short
for "AUXilliary  storage BOXES"  and  we  pronounce  it  "OX
BOXES")  1, 2, 3 and 4, would look like this:

          \MARQUE #1,#2,#3,#4

     If auxbox  #1 contained  the value 20, #2 contained 24,
#3   contained 40,  and #4  contained 50, then this would do
the EXACT SAME THING as in the previous examples.
     Syntax requires that auxboxes be described with a pound
sign (#)  in front  of them, unless you had previously named
the auxbox, in which case you could specify the name instead
of the  number.  There cannot be any signs (+,-) between the
pound sign  (#) and the auxbox number.  If the pound sign is
not present,  the program  thinks it  is  seeing  a  numeric
literal if  the first character is a number (0 through 9) or
the plus (+) and minus (-) signs.  If the first character is
a letter,  it assumes  you are  using a named auxbox, unless
the name  is ONE  AND ONLY ONE character long.  In this case
the program  assumes you  are referring to one of 26 special
numeric variables (see below).
     The auxboxes  don't have  to contain numbers.  They can
also  contain  "literals"  (alphanumerics).    For  example,
TIME&DATE  is   an  alphanumeric   literal,  not  a  number.
Alphanumeric auxboxes  can be  up to 80 characters long.  If
you try  to use  an auxbox  that has  non-numeric data in it
when you need a numeric value...it's an error.  Also, if you
have not  set an  auxbox to a value before trying to use it,
that's an error too (auxboxes don't actually exist until you
put something  in them.)   Auxboxes can be switched back and
forth  from   numeric  to  alphanumeric  values  or  removed
entirely to make room for new ones.


     VARIABLES
     When the  program encounters  a solitary letter where a
value is  expected it is interpreted as a variable, which is
always numeric,  and the  value in  that variable is used in
the command.   These  are very much like algebraic variables
except for variables A through F.  The program AUTOMATICALLY
puts values  in those six, so don't try to use them to store
anything!  Some other commands will put values in additional
variables (for example \SET.)

     Here are some more examples of valid command syntax:

          \ADD (8 + 16) TO Q
          \LINE (M*3),(N+80),(O-160),(P+ #434),#23
          \READ GREETING.PIC
          \BUILD #23="Today is ",TIME&DATE[1,8]
          \"


     SYNTAX
     Wherever a  pound sign  (#) appears  in  the  following
command listing  it can mean several things.  If it is where
a numeric  value should  be, it  can be an auxbox, variable,
number or  mathematical expression  containing any  of these
elements.  If it is where an alphanumeric value should be it
must be  an auxbox (not a variable), or in most cases can be
an alphanumeric literal inside quote marks.
     Start alphanumeric  literals with  a single or a double
quote and  end them  with whichever  (single or  double) you
started them  with.   To specify a numeric literal just type
the number.   To  specify an  auxbox type  the number of the
auxbox with  a pound  sign (#) in front of it, such as #123.
If the  auxbox is  named you  may use the name.  A number of
commands  (such   as  \DISPLAY)   allow  either  numeric  or
alphanumeric values in each position.
     Braces ({,})  are used  in this manual to indicate that
several different  things can be put there, or that optional
parameters may  be  included.    Do  not  code  the  braces.
Brackets ([,])  on the  other  hand  should  be  coded  when
indicated.   They refer  to characters  within  alphanumeric
auxboxes.
     A mathematical  expression must be constructed entirely
of mathematical  parts.  You  may  use  any  combination  of
parenthesis  (   (  )   ),  operators  (+-*/)  and  operands
(auxboxes, numbers  or variables).   Evaluation is standard:
things inside  of  parenthesis  are  evaluated  first,  then
multiplication and  division operators  are  evaluated  with
equal precedence,  then addition  and  subtraction  equally.
Aside  from   these  rules,   evaluation  is  left-to-right.
Internal calculations  are  handled  as  signed  double-word
values.   This means  the intermediate results can be signed
values up  to 31  bits long.   The  final  total  should  be
between -32K and +32K to be handled properly.  The following
statement would  be valid if auxbox #323 contained a numeric
value and variable R was not 0:

          \MOVE (M*N)+O+#323-P+(Q/R) TO S










                     **** ACTIVATE ****


FORMAT: \ACTIVATE {SCREEN #}


     Screen 0  is the actual screen while screen 1 is the
     normal background  screen.   By activating screen 1,
     all \SHOW,  \RUN, \LINE,  \CIRCLE,  \DOT  and  other
     pixel-writing  commands   write  to  the  background
     screen.   Also all  text displayed  with the current
     font is  written to  the activated screen.  The only
     things that  are NOT  written to the activated frame
     are text  which uses the DOS font (including numeric
     display, lines  displayed and  entered by  the  user
     with the  \QUESTION command,  and text displayed for
     the \WAIT  RETURN command and when the ESCAPE key is
     pressed.)

     This function  is especially  useful  for  designing
     complex images which you will want to display all at
     once.  You can create them while the user is reading
     something else on the screen.

     The  background   frame  is   also  used   for  MASK
     operations. The image that is brought forward during
     the \SHOW  of a  masked  frame  is  taken  from  the
     background screen  and then  the  merged  frame  and
     background are  moved  to  the  screen.    Therefore
     although most  image display  commands can  write to
     any screen  (0,1...), masked  frame should  only  be
     written to  screen 0.   Otherwise unexpected results
     may appear.

     Any error, even if trapped, will activate screen 0.



                        **** ADD ****


FORMAT: \ADD # TO #


     Must be  numeric.  The first # can be a mathematical
     expression.   The second  # must  be a  variable  or
     auxbox.  The result will overlay the second value.


EXAMPLES:

     \ADD #24 TO #8
     \ADD #24*#43 TO #12

     (The second  example multiplies  the contents of auxbox
     24 by the contents of auxbox 43 and adds the product to
     the contents of auxbox 12, putting the result in auxbox
     12.)



                      **** APPEND ****


FORMAT: \APPEND NNNNNNNN.PIC #,#


     The specified  frames from the named picture file on
     disk are appended to the current file in RAM or EMM.
     This means  they are  tacked on  to the  end of  the
     file.   The frames  can all be shown in one animated
     sequence.   It is  a good  idea to  \APPEND as  many
     frames as  possible at  once.   It  is  faster,  and
     whenever you  add single  frames DOS has to give the
     program smaller,  more wasteful  chunks of RAM. This
     can fragment  the use  of your  computer's memory if
     you  continually   are  \APPENDing   and  \DELETEing
     frames. Instead,  \READ in  a new  picture file when
     possible so the program will return all the previous
     allocations of RAM or EMM to DOS and start fresh.

     After your  \APPEND frames you will need to refer to
     the frame  #'s as  they exist  in RAM or EMM--not by
     their numbers in the original file.

     If the  second value is -1 the program will read the
     entire picture file.

     The #  of frames  that were actually read will be in
     variable "A".

     When creating/testing  a text file this command will
     execute each  time it  is encountered.    Therefore,
     your picture  file can  get very  big very  quickly.
     You  will  have  to  get  around  this,  perhaps  by
     commenting out  the line temporarily by inserting an
     asterisk (*)  in the  second column  while you  test
     your text file.  Don't forget to remove the asterisk
     when you save the text file!

     \APPEND can  be used to salvage damaged files.  If a
     picture file  is invalid for any reason it cannot be
     \READ but it may be possible to \APPEND some or even
     all of  the frames.  Dust particles on a diskette or
     "head  crashes"   could  all   create  invalid  file
     conditions.     Do  not   expect  \APPEND  to  solve
     anything!  Maintain multiple backups!



                     **** AUTHORITY ****


FORMAT: \AUTHORITY {HIGH}


     In order to use the \OUT command you need to set the
     AUTHORITY LEVEL  to high.   This  merely allows  the
     \OUT command  to execute.  OUT is very powerful--you
     should KNOW WHAT YOU ARE DOING BEFORE USING THE \OUT
     COMMAND.   IT IS  NOT REPEAT  NOT TO BE PLAYED WITH.
     It will  write directly  to the  hardware.   You can
     crash the system or even BREAK THE MONITOR and other
     parts if  you \OUT garbage.  I'm SERIOUS.  DON'T USE
     \OUT UNLESS YOU UNDERSTAND WHAT IT WILL DO.

     That's why you have to enable \OUT with \AUTHORITY.






                       **** BEEP ****


FORMAT: \BEEP #{,#}


     Beeps the  speaker for the duration specified in the
     first number.  The first number represents a unit of
     time equal to that used with the SPEED option of the
     \ROUNDS command  and other  commands. A value of 584
     will be about one second. A value of zero clicks the
     speaker.   Maximum value  is 10,000.    Duration  is
     preset to 23.

     If the  \CLOCK speed  has been  set differently from
     the  default,   the  length  of  the  beep  will  be
     proportionately changed.

     The optional  second number  is the  tone in cycles-
     per-second.   If present  it must be greater than 20
     or it  will be  ignored.   Tone  is  preset  to  988
     cycles/second.

     \SOUND OFF will override this command.



                       **** BLANK ****


FORMAT: \BLANK #,#,#,#


     Will blank  a rectangle on the screen from the first
     two values  (X-low, Y-low)  to the second two values
     (X-high, Y-high).



                       **** BREAK ****


FORMAT: \BREAK {ON} or \BREAK OFF


     This command is a debugging tool and is not expected
     to ever  be used  in a  finished tutorial.  It turns
     "single-step" mode  on and  off.  You can also begin
     single-step  operation   by  pressing   ESCAPE   and
     following the prompts.  To turn single-step mode off
     again, press ESCAPE and don't turn the option on.

     In single-step  mode the  next line  to be  executed
     will appear  at  the  bottom  of  the  screen.    If
     multiple commands  appear on the same line they will
     all be  shown and  THEY WILL  ALL BE EXECUTED in the
     next cycle.   After  displaying the line the program
     waits for  you to  press a  key.  That key goes into
     the program  as if  you had pressed it in the normal
     course of  running the  tutorial--it is NOT absorbed
     by the  "single-step" operation.    Macros  are  NOT
     single-stepped.

     During single-step  mode all \ON KEY jumps and calls
     will be  taken except the "global" option.  However,
     the \X  NNNNN (paragraph)  that the command jumps to
     will NOT  be shown,  nor will  any commands  on that
     line or  connected by \+.  This is because lines are
     only displayed when user keypresses would be checked
     for.  This is also true for \CALL's and \JUMP's--the
     paragraph name lines (\X NNNNN) will not be shown.



                       **** BUILD ****


FORMAT: \BUILD #=#{,#,# etc.}


     This command  creates an  alphanumeric auxbox out of
     other auxboxes, or even pieces of other auxboxes, or
     numbers, or literals (in quotes).  The maximum total
     length is 80 characters.  Separate each element with
     commas.


EXAMPLE:

     \MOVE "HELLO " to #4
     \BUILD #3=#4,"THERE!"
     \DISPLAY #3   ;(HELLO THERE! is displayed)



                      **** BUTTON ****


FORMAT: \BUTTON 1=# 2=# 3=#...7=# or 0


     Gives an alternate key value for any of seven button
     codes used  by the  mouse, joystick,  or  digitizer.
     The normal  (default) key  value for  all buttons is
     7181, the  return  key.    Values  do  NOT  have  to
     correspond to actual key values.

     If the  input device supplies a button value greater
     than seven  it is automatically assigned the keycode
     7181.

     \BUTTON 0  (zero) will  ask the user to enter button
     presses and  press  a  key.    This  gives  them  an
     opportunity to  adjust the  buttons to  what is most
     convenient for  them.   The button  presses that the
     user responds  with will  be remapped to the first 3
     button values and to no (0) buttons pressed.

     NOTE:   For codes  corresponding to  multiple button
     presses, the  program will "probably" respond to the
     first button  first, as  it is  almost impossible to
     press the buttons at the exact same time.  Similarly
     when releasing  multiple buttons,  an indication  of
     other combinations is likely to occur.  Thus single-
     button functions are most reliably reported.



                       **** CALL ****


FORMAT: \CALL NNNNN


     NNNNN is  a name  of a  place in your text file (see
     the \X  command).    The  name  can  be  one  to  30
     characters long  with no  imbedded spaces.  The name
     must be exactly the same, including capitals and all
     other characters,  in all  places it  appears or you
     will not  be able  to reference  it correctly.   The
     difference between  \CALL and  \JUMP is that \RETURN
     will  return  processing  to  the  instruction  that
     follows  the  \CALL.    The  instructions  that  the
     program does  between the  \CALL  and  the  matching
     \RETURN are  called a  subroutine.  A subroutine may
     call other  subroutines, and  the current call could
     in turn  have been  called... You  can go thirty-two
     (32) deep before you get in too deep and the program
     can't process.  (An error message appears.)



                       **** CALLM ****


FORMAT: \CALLM NNNNN


     Use this  special form  of the \CALL command to call
     paragraphs within  macros from  text files.   Within
     all macros,  you are  expected to eventually \RETURN
     to the  calling text file, or return with an \ON KEY
     or \READ command.

     Once inside a macro use the regular \CALL command to
     call other paragraphs within the macro area.

     When you read in a new text file all nested \CALL's,
     \CALLM's and  \IF's are reset, and processing begins
     at the  start of  the text  file.   This will happen
     even if  the program does not actually read the file
     because it is already in RAM (see \READ).



                      **** CIRCLE ****


FORMAT: \CIRCLE {ANGLE=#,# COLOR=# LOCATION=#,#
          RADIUS=#,#}


     Draws a circle, oval, or arc by one of two methods.

ANGLE=#,#
     If specified  the program will use a lookup table of
     sine values  to calculate  the endpoints of 1-degree
     connected line  segments.   If you  draw a  complete
     circle  by   not  specifying   any  angle   (not  by
     specifying   0,360)    it   calculates    the   dots
     mathematically using the Pythagorean Theorem.

COLOR=#
     If  in  XOR  mode  when  executed,  will  produce  a
     speckled circle  because some  dots are  drawn  more
     than once.

LOCATION=#,#
     Is the  location of  the center  of the  circle.  It
     need not be on the screen.

RADIUS=#,#
     Is the length of the radii on the X, Y axis.  ANGLES
     are only "correct" (circular, not oval) for radii of
     10:12 ratio--the ratio of the individual dot's width
     to height  on a  standard CGA  monitor  with  a  4:3
     ratio.   Other ratios  will affect  the actual angle
     that a  specified angle is drawn at.  Maximum radius
     on either axis is 2000.





                       **** CLEAR ****


FORMAT: \CLEAR {KEYBOARD, MACROS, NAMES,  ON KEYS,
          PICTURES, SCREEN, SHOW, SPRITES, SPRITE #}


     Resets parameters  to "standard"  values.   Use only
     one option at a time.

KEYBOARD
     Clears all keys out of the keyboard buffer.  The key
     values are  lost.    The  program  always  gets  ONE
     keypress (if available) between each command line or
     cycle of  animation and puts it in variable "B".  It
     is therefore  unlikely that the keyboard buffer will
     ever fill  up, except  when executing  commands that
     take a  long time  to process.  \DRAW with the PAINT
     option and  \READ are  both candidates.   Of course,
     the user  would have to be pressing a lot of keys or
     holding one down.

MACROS
     Clears the  macros you  have read  so far  and their
     names.     The  program  stores  up  to  nine  macro
     filenames that  have been read as well as the macros
     themselves.   This command clears out both the names
     and the  macros.  You can read more than nine macros
     without \CLEARing  if  they  will  fit  in  the  10k
     (approximate) available,  but the  names will not be
     stored.     \READ  will   reread  the  macro  if  it
     encounters a name it hasn't stored, possibly filling
     up your  macro area.  You can  use \DELETE to remove
     specific macro filenames without \CLEARing the macro
     area.     This  command  also  clears  any  \ON  KEY
     specifications that refer to paragraphs in the macro
     area.

MOUSE
     Sets mouse  options to  default values.   See \MOUSE
     for what  these values are.  The \SCREEN command, if
     it changes  the current  mode, will execute a \CLEAR
     MOUSE command automatically.

NAMES
     Clears all  symbolic auxnames that you have created.
     No auxbox  data is cleared; it may still be referred
     to by  auxbox number.   Reading  new text  files and
     using the editor does NOT clear auxbox names.

ON KEYS
     Clears all  \ON KEY specifications either for macros
     or for  text depending  on where the command appears
     (it clears  only the  one it's  in).   You need  not
     specify which  one to clear.  The program clears the
     macro specs if you are in a macro and the text specs
     if you aren't.

ON ERROR
     Clears the  \ON ERROR  command, making  the  program
     stop on any error again (That's the default.)

PICTURES
     This removes all pictures in RAM or EMM from memory.
     Use before  changing screen modes because you cannot
     change to incompatible modes (different resolutions)
     while you  have pictures  in RAM or EMM.  You cannot
     use this  option if  you have changes to the current
     file or  if you  are in  the picture  editor at  the
     time.

SCREEN
     This is  a fastest  way to  clear the  screen.  Will
     clear the  background  screen  if  it  is  currently
     active.

SHOW
     This clears  the parameters  set up with the keyword
     options of \SHOW.  WINDOW is set to the full screen,
     AND=NO, OR=NO,  XOR=NO,  PATH=NO,  LOCATION=0,0  and
     MOTION=0,0.   The \SCREEN command, if it changes the
     current mode,  will execute  a \CLEAR  SHOW  command
     automatically.

SPRITES
     Clears all  sprites  that  have  been  set  up  with
     \SPRITE and  \SPRINT  and  resets  all  the  \SPRITE
     parameters to the default values listed in \SPRITE.

SPRITE #
     Clears one  sprinted frame  or  resets  the  \SPRITE
     values  to   their  defaults  without  clearing  any
     frames.  To use this option to clear a single sprite
     element you must keep track of which frames were set
     up with  \SPRINT and  in what  order.   To clear the
     first sprinted  frame use  1, the  second, 2 etc.  A
     value of  zero (0) will reset the \SPRITE parameters
     but will NOT clear the elements you have already set
     up.



                       **** CLOCK ****


FORMAT: \CLOCK SPEED=# CURSOR=#,# FORMAT={MM:SS,
          HH:MM:SS, HH:MM,SS}


     Clock serves  several functions.   It can be used to
     set the  number of  times that  the PC  Asynchronous
     Clock interrupt  occurs each second (SPEED= option),
     or to  display the  current time  somewhere  on  the
     screen.   When displaying  the time  only the digits
     that change are updated, except the hours digits are
     updated with  the minutes  digits.   If you  place a
     drawing  or   text  over   the  clock  it  will  not
     completely reappear  immediately. If a \CLEAR SCREEN
     or similar  command is  executed  the  entire  clock
     display will be rewritten.

SPEED=#
     Specifies the number of times the asynchronous clock
     should cause  an internal  software  interrupt,  per
     second. Values  are from  1 to  6 where  one is  the
     standard DOS  amount, about  18.2 times  per second,
     and each  unit above  (2, 3 etc.) is twice as often.
     The default  is 5,  or about  584 times  per second.
     This provides  enough control  for most applications
     without taking too much "overhead" in CPU usage.

     This value  is temporarily  reset  to  the  standard
     value, 18.2,  during the  \EXECUTE command.   It  is
     also reset on exit.

CURSOR=#,#
     Specify the  position of  the on-screen clock on the
     screen.   Values are in characters on the X, Y axis,
     where 0,0 is the upper left corner of the screen.

FORMAT={MM:SS, HH:MM:SS, HH:MM,SS}
     Lets you  specify how  much of  the current time you
     would like  to display.  The format HH:MM will blink
     the colon  every second,  other formats  update  the
     hours and minutes only once a minute.



                       **** CLOSE ****


FORMAT: \CLOSE NNNNNNNN.EXT or LPT#:


     This closes  a named  file or  turns off  access  to
     LPT#: (the  system printer).   NNNNNNNN  is the file
     name.   The extension  can be DAT, PIC, or PRN.  The
     file must  have previously  been opened  with \OPEN.
     Errors in  processing will  cause these  files to be
     closed automatically  when processing  stops.   They
     will also be closed if you exit to DOS.

     Files must  always  be  closed  if  they  have  been
     written to,  so that  the file directory information
     that DOS  maintains will  be properly  updated.  For
     all manual  operations  with  the  editor  and  when
     writing auxiliary  files, this program automatically
     closes files after it writes them.

     Closing LPT#:  (where #  is 1,  2, or  3)  does  not
     actually signal  the printer  in any  way, it simply
     disables access to it with \PRINT. You might do this
     so that  you can  use the  statement to  write print
     files to disk.


EXAMPLES:

     \CLOSE LPT1:
     \CLOSE SOANDSO.PRN



                      **** CONNECT ****


FORMAT: \CONNECT {ON or YES} or {OFF or NO}


     This will  cause vector  images  to  be  drawn  with
     connected dots in the picture editor and with \SHOW.
     To  draw   connected  dots   with  sprites  use  the
     CONNECT=YES option  of \SPRITE.   The  color of  the
     line that is drawn will be the color of the upcoming
     dot.  The starting dot of each line segment will not
     be drawn  after the  first one  in the  image.   The
     connect option  is initially  OFF.  \CONNECT with no
     parameters defaults to turning connected mode ON.

     The lines  are clipped  if the endpoints are off the
     screen.   In Version  7.24 if the endpoints are more
     than 32767  dots apart on any axis a sign conversion
     error may  occur during  internal calculations,  and
     the  line   will  not   be  drawn  properly.    This
     separation corresponds  to more  than 100  times the
     width of  the screen  in the  CGA mode  and over 150
     times the CGA height of 200 dots.


EXAMPLES:

     \CONNECT NO     ;turns it off
     \CONNECT YES    ;turns it on




                      **** CONVERT ****


FORMAT: \CONVERT #


     This will  convert an auxbox from an alphanumeric to
     a numeric  or from a numeric to an alphanumeric.  It
     is up  to you  to know  which way you are going.  If
     you are  going from an alphanumeric to a numeric and
     the  alphanumeric   starts  with  numbers,  it  will
     convert the  numbers  only.    Numbers  that  become
     greater than  32767 or less than -32768 will produce
     an error.  The alphanumeric auxbox produced when you
     convert from  a number  is six  bytes long  and will
     contain "leading"  (left-hand) spaces  in  place  of
     high-order zeroes,  with a  minus sign (-) if needed
     next to the leading character.  Non-numeric auxboxes
     are displayed  with the  current font  at a location
     set by  the \LOCATE  command.   Numeric auxboxes are
     displayed with the DOS font, and the cursor position
     is then set with \CURSOR.


EXAMPLES:

     \MOVE 328 TO #80
     \CURSOR 0,0
     \DISPLAY #80    ;328 is displayed as a numeric
     \CONVERT #80
     \LOCATE 0,10
     \DISPLAY #80    ;328 displayed in the current font
     \DISPLAY #80[4,2]    ;32 is displayed.




                       **** CRAWL ****


FORMAT: \CRAWL #{,X or A or O,#}


     This sets  text display  mode to CRAWL from right to
     left.   The first  number is the speed of the crawl,
     the second  parameter if  included should be an X to
     XOR the text onto the screen, or an A or O to AND or
     OR the  text.   If the text is to be XORed, ANDed or
     ORed, then  a third  value should be included as the
     color to  XOR, AND  or OR  the text  with as  it  is
     placed on  the screen.    Like  \SCROLL  and  unlike
     \OVERLAY it  does not  XOR, AND  or OR the text with
     what is already on the screen.

     The area  to be  crawled is set with \LOCATE for the
     upper left corner, and \WIDTH.  All \CRAWLed text is
     one character high.

     Anything in  the crawl  area that  was there  before
     will be shifted off the screen.

     This command  gives the effect of an electronic news
     banner crawling through a window from right to left.

     AND, OR,  and XOR are most useful for fonts designed
     with just black (background) and the highest numeric
     color available for the screen mode.

     Special considerations for BITPLANE modes:

     With \SCROLL and \OVERLAY, in bitplane modes you can
     only XOR, AND, or OR with color 1.  Use \TEXT PLANE=
     for effects similar to what other color values would
     give you in  bitmapped modes.

     OR has  no effect  in bitplane  modes (will work the
     same as XOR).

     AND with 0 has no effect in ANY mode.



                      **** CURSOR ****


FORMAT: \CURSOR #,# {,#,#}


     This sets  a cursor  for user input and numeric data
     output.   The screen  in this case should be thought
     of as  being cursor  positions.    See  the  \SCREEN
     command for a table of character dimensions for each
     screen mode.  The upper left corner is position 0,0.
     In CGA  mode, which is 320 by 200 dots, there are 40
     X 25  cursor positions.   The  first  value  is  the
     column (0-39)  and the  second value  is the row (0-
     24).  The bottom right position of the screen is not
     available because DOS would scroll the entire screen
     if a character is placed there.

     The second  two numbers, if present, create a window
     for user  input and numeric data output.  The cursor
     will be  set to  the upper  left corner  (the  place
     specified by  the first  two numbers.)   Text  lines
     that are  too long  for the available window will be
     automatically scrolled for the user.



                       **** DATA ****


FORMAT: \DATA  #{,#,#...}


     This command  reads ASCII data into auxboxes in P11.
     The file  should be  delimited by  commas  for  each
     field and  by 13,10 (carriage return, line feed) for
     each record.  Each \DATA statement reads ONE record.
     Maximum record  length is  512 bytes  including  the
     13,10.   Each field  is placed  in the corresponding
     auxbox, by position.

     You should  \ELIMINATE the  auxbox(s) you  will read
     data into  before  executing  the  \DATA  statement.
     That way if the auxbox(s) still don't exist you know
     you read the last record or a blank (empty) record.



                      **** DELETE ****


FORMAT: \DELETE {FRAME #} {MACRO NNNNNNNN}


     The FRAME  option of  this command  will delete  the
     frame requested from the current picture file in RAM
     provided there are no changes to that file since the
     last save.   This command will only return the space
     to DOS  if the  frame being deleted is the sole user
     of the  associated chunk  of RAM.  See Appendix "E",
     Space Considerations, for more information.

     The MACRO option will delete the macro name from the
     list of stored names.  IT WILL NOT DELETE THE MACRO!
     This is  so you  can more easily control which macro
     names  are  stored.    When  a  \READ  statement  is
     encountered and  the name  matches one  of the  nine
     stored macro  names, the  read is  skipped.  You may
     use \CLEAR  to remove  all the  macro names but that
     also removes the macros.


EXAMPLES:

     \DELETE FRAME 23
     \DELETE MACRO SETNAMES



                     **** DIGITIZER ****


FORMAT: \DIGITIZER {OFF}, {INITIALIZE #,#{,#{,#,#}}}, or
          {?}


INITIALIZE
     Turns the  digitizer on.   The first two numbers for
     X, Y  axis resolution  are not adjusted before being
     passed to  the digitizer  so be  sure to account for
     any rounding  that  the  digitizer  will  do.    The
     default values  (in CGA  mode) are 328 on the X-axis
     and 298  on the  Y-axis.   Refer to your digitizer's
     manual for  more information.   The  third number if
     present should  be a two or a one (2 or 1).  If two,
     COM2  rather   than  COM1   will  be   used.    (The
     communications port COM1 is located at address 3F8h,
     while COM2 is at 2F8h.)

     The fourth  and fifth  numbers are  the X-offset and
     the Y-offset,  if you  don't want  offset 0,0.   The
     offset is  added to  the screen  X,Y position to get
     the minimum axis values.  You may prefer a border on
     the right as well as the left.

OFF
     Turns the digitizer off if it was on.

?
     Returns the  current state  of the  digitizer. 0  is
     off, 1  is off, but had previously been on, and 2 is
     currently on.  Value is returned is variable "A".

     Turning on  the digitizer  turns off  the  mouse  or
     joystick if they are on.

     If you  change screen  modes you  should  reset  the
     digitizer, because the maximum X- and Y- axis values
     may be incorrect for the new screen mode.



                      **** DISPLAY ****


FORMAT: \DISPLAY #{,#,#...}


     Will display text or numbers on the screen.  Numbers
     are displayed  using  the  DOS  standard  font,  and
     always on  the actual  screen, wherever  \CURSOR set
     the cursor.   Alphanumerics,  including literals  in
     quotes,  are   displayed  using   the  current  font
     wherever \LOCATE  set the text cursor, on the active
     screen (see  \ACTIVATE.)   Additional items  can  be
     displayed when  separated by  commas.   Any  literal
     auxbox can  have just  a portion  of it displayed by
     immediately following  the name  or #  with brackets
     and two numbers:

     \DISPLAY #45[12,23]

     The first  number in  the brackets  is the  starting
     position to  display and  the second  is the length.
     These numbers  can  be  variables  or  even  numeric
     auxboxes.   Do not  use the  tab character  within a
     \DISLAY sequence.


EXAMPLES:

     \DISPLAY "Today is ",TIME&DATE[1,8]
     \DISPLAY A,B,C,#1,#45,#32767

     In the second example, first the variables A, B, and
     C will  be displayed  using the DOS character set at
     the current numeric cursor location, and the numeric
     cursor location will be advanced by seven places for
     each variable  displayed.   If there  is not  enough
     room (seven  characters) the cursor will be advanced
     to the  next line and to the top of the screen if at
     the bottom.  The placement of auxboxes #1 and #45 in
     this example  would  depend  on  whether  they  were
     numeric or  not.  Auxbox #32767 (TIME&DATE) would be
     displayed wherever the non-numeric cursor is set (in
     the current  font)  and  would  advance  the  cursor
     according to the width of the font.  (See \LOCATE.)



                      **** DIVIDE ****


FORMAT: \DIVIDE # by # {REMAINDER #}


     Don't divide  by zero, of course.  The second number
     can be  a numeric  literal,  mathematical  equation,
     numeric auxbox  or variable.   The first number must
     be a  numeric auxbox or variable.  The result (aside
     from the remainder) goes in the first value, and the
     remainder (if  specified) goes  in the  third value.
     REMAINDER is  optional.   If used only the first few
     letters (REM)  are actually  needed.  REMAINDER must
     follow the second number by at least one space.


EXAMPLES:

     \MOVE 32000 TO #48
     \DIVIDE #48 BY (34*55) +16000 REM A
     \DISPLAY #48,A

     1 and  14130 are  displayed on  the screen.  First, the
     portion referenced  by the word BY is evaluated so that
     the program knows what to divide #48 by.  (34*55)+16000
     is equal  to 17870.   Dividing  32000 by  17870 gives 1
     with a remainder of 14130.



                        **** DOT ****


FORMAT: \DOT #,#,#{,X or A or O}


     The first  two numbers are the X, Y location for the
     dot.   The third  number is  the color  of the  dot,
     where zero  is the background color. The optional ,X
     (comma X) will XOR the dot onto the screen.  ,X will
     also turn  on XOR  mode for  future \DRAW  and \LINE
     commands.   Similarly, A will turn on AND mode and O
     will turn  on OR  mode.   Another  \DOT  command  is
     needed to turn off XOR, AND and OR.  To just turn on
     XOR or  OR without actually drawing anything, draw a
     background dot:   This  command  writes  a  dot  but
     background (0)  XORs to  produce no change.  To just
     turn on  AND, write  a foreground  dot (whatever the
     current screen  mode allows  as  the  highest  value
     dot.)   If the  third option  is a question mark (?)
     the color  of the  dot at  the location specified is
     put in  variable "A".   In this case do not use XOR,
     AND, or OR.

     \PEN can  also be  used to  turn on XOR, AND, and OR
     mode.



                       **** DRAW ****


FORMAT: \DRAW {UDLREFGH}#, C#, J#,#, M{+,-}#,{+,-}#, P
          #,{UDLRHVA}, S{X,Y or A}


     All parameters  here are  one letter  and then  some
     numbers or  letters or  whatever.   The options that
     belong  to  each  parameter  follow  that  parameter
     immediately without spaces, except P (Paint).

     Commas are  not necessary  to separate  the elements
     providing the  syntax is  still understandable.  For
     example the two values that follow the "J", "P", and
     "M" options must be separated by commas, but options
     need not be.

     \DRAW functions  more or  less as  a series  of line
     segments.

J#,# will   Jump  to that  spot on  the screen without
     drawing.

UDLREFGH# will move # dots in the direction specified-
     -Up, Down,  Left, Right  and E, F, G, and H which
     go at  angles.   For example  one dot to the left
     and one  up is  H while  one dot to the right and
     one down is F.

C# is  a Color,  but C  followed by  just a comma (C,)
     sets the current color to clear (which is not the
     same as blank.)

S{X, Y or A}# is the Scale amount. X changes the scale
     for the  X-axis, Y  changes the scale for Y-axis,
     and A  changes them  both.  A number follows X, Y
     or A.   8  is unscaled, so 4 is half scale and 16
     is double  scale.  The X, Y or A must immediately
     follow the S with no spaces.

P is  the only draw command that should be followed by
     one or  more spaces  after the letter.  It stands
     for Paint  and IS the Paint command, but use only
     one letter to describe it.  (See \Paint).

M {+,-}#,{+,-}# is Move.  M will draw from the current
     cursor  location   to  the   spot  named  by  the
     coordinates #,#  that follow the M. The line will
     be in  the current  color   If  you  precede  the
     numbers with  a +  or  a  -,  the  move  will  be
     relative to  the initial cursor position.  Both X
     and Y must be specified even if they are 0.



EXAMPLES:

     \DRAW P 2,D,C2R33M+20,-35J40,43C,R22

     IS THE SAME AS:

     \DRAW P 2,D,C2,R33,M+20,-35,J40,43,C3,D4,C,R22

     In the  above example,  Paint mode is first set to a
     border color  of two (2) (red in palette 0 of CGA 4-
     color mode),  and aimed down.  Then the color is set
     to two  (2) and  the cursor is moved to the right 33
     units, painting  as it  goes.  The starting position
     was not  specified so  the  command  would  use  the
     current position.   Then the cursor moves to a point
     20 dots  to  the  right  AND  35  dots  down,  still
     painting as  it goes.   Next  it jumps  to  location
     40,43 WITHOUT  DRAWING ANYTHING.  Then  we  set  the
     color to  3 (yellow  in CGA palette 0) and draw down
     four dots.   Then  the color  is set to clear and we
     move right  22 units,  perhaps so  that another draw
     command can do something there.



                     **** ELIMINATE ****


FORMAT: \ELIMINATE #,#,# TO #,# TO # etc..


     Eliminates auxboxes  from the  auxfile in  RAM.  You
     can delete one (1) or all (except the 32767th, which
     is TIME&DATE).  Commas are used to separate boxes to
     be removed.   When  the word TO separates the auxbox
     numbers, the  range, inclusive,  is removed.   It is
     important to remember two things about this command:
     First,  you   cannot  use  symbolic  names  or  math
     equations or  variables to  specify the locations to
     be eliminated.   The expressions must be #23, #45 TO
     #87, and  so on.   They are NOT evaluated--the first
     one just  listed would remove auxbox 23, not the one
     represented by  the value stored in 23.  Second, the
     symbolic name  is NOT  removed.   It still refers to
     this box. (Names are removed with \CLEAR NAMES.)

     A \READ  will NOT  read the  aux file  if it  is the
     exact same name as the aux file already in RAM.


EXAMPLES:

     \* this command clears all auxboxes except,
     \* of course, the TIME&DATE auxbox.
     \ELIMINATE #1 TO #32766



                       **** ELSE ****


FORMAT: \ELSE


     Part of IF-THEN-ELSE statements.  See \IF.  When \IF
     statements are  evaluated, they  are either  TRUE or
     FALSE.     If  they   are  false,  they  go  to  the
     corresponding   \ELSE    statement   (skipping   any
     subordinate \IF's  and the  \THEN's and \ELSE's that
     accompany them).

     Either  the  \THEN  or  the  \ELSE  clause  and  any
     accompanying actions  can be  left off, but to leave
     both off would be totally useless.


EXAMPLES:

     \IF #34 = 233
     \ELSE
     \JUMP NEXT_CHECK
     \ENDIF
     \IF #54 = "5"
     \MOVE 4 TO G
     \ENDIF
     \X NEXT_CHECK
     \IF T = 76
     \THEN \MOVE 6 TO Q
     \ELSE \MOVE 4 TO Q
     \ENDIF



                        **** END ****


FORMAT: \END


     Stops processing  and returns  you to the editor, or
     returns processing  to  DOS  if  using  the  runtime
     version.

     When the  program returns  to DOS it passes a return
     code as follows:


     0--Normal   exit--either    with   this    command   or
     interactively through F6.

     1--An error  occurred (errors are listed in the back of
     this manual).

     2--A critical error occurred--most likely a disk error,
     but possibly a character device error.

     3--Both an  error and  a critical error occurred.  This
     is difficult if not impossible to achieve.




                       **** ENDIF ****


FORMAT: \ENDIF


     Ends an  IF-THEN-ELSE   statement.   See \IF.   This
     statement must  come before an \X command (paragraph
     name) coded in-line (sequentially) in the text file.
     However, you  can \JUMP and \CALL your way out of an
     \IF statement  or even  read in  a new  text file or
     \END the program.

     \ENDIF ends all nested \IF statements that have been
     coded in-line.   It does NOT end \IF statements that
     were in process when a call occurred, only the one's
     SINCE the last call.


EXAMPLES:

     \IF #32<999
     \ADD 1 TO #32
     \ELSE
     \MOVE 0 TO #32
     \IF C=3
     \MOVE 0 TO C
     \ELSE
     \ADD 1 TO C
     \ENDIF



                       **** ERROR ****


FORMAT: \ERROR ?


     Places the last (most recent) error code in variable
     "A".   It has  no other  purpose.  Use \ON ERROR for
     error trapping.



                     **** EXCHANGE ****


FORMAT: \EXCHANGE SCREENS


     If you have saved a screen with \SAVE SCREEN you can
     exchange (swap)  the current  screen with  the saved
     screen using  this command.   The screen is saved to
     the background  screen, screen  1.  (See \ACTIVATE.)
     The background  screen is used for raster frame mask
     operations.

     If you  have set  B:0 in  the environmental variable
     P11FLAGS=  or  in  the  startup  parameters  on  the
     command line, then the screen will be exchanged with
     a previously saved version on disk, in the \P11\TEMP
     directory.   That directory  MUST exist and a screen
     must be  saved in  it before using \EXCHANGE SCREEN.
     This will  toggle the  name  of  the  current  saved
     screen between  SCRNDUMP.SV1  and  SCRNDUMP.SV2,  so
     there must  be enough  disk  space  for  two  entire
     screen images in order to use \EXCHANGE SCREEN.



                      **** EXECUTE ****


FORMAT: \EXECUTE DOS> and then anything you would type at
          the DOS prompt, or \EXECUTE > and then a
          program you wish to load and execute (run).


     This command  does not  "exit" to  DOS.   Instead it
     will load  and execute  the named  program or load a
     second copy  of the COMMAND PROCESSOR (DOS) and give
     it the  command (if  any) that  follows the  greater
     than (>) sign.

     Legitimate commands  could be anything that will fit
     in  memory.     See  Appendix  "N"  for  a  complete
     discussion of  this powerful command.  What you code
     after the  >  is  not  evaluated  for  variables  or
     auxboxes.   It is  given directly to the second copy
     of DOS,  or  simply  used  to  load  and  execute  a
     program.   Therefore drive  specifications  are  NOT
     variables or auxboxes.  Drive "A" is drive 1,  drive
     "B" is  drive 2  and so on.  Use forward slashes (/)
     for  pathnames:   this  program  will  reverse  them
     automatically (up  to the first space).  A backslash
     would indicate  another command on the same line for
     this program.   If you want to use a backslash after
     a space,  you can  use  an  auxbox  to  specify  the
     command line:   Use  a parenthesis  and specify  the
     auxbox within the parenthesis: \EXECUTE >(#454)

     As of  version 7.30  you can  do an  \EXECUTE with a
     PRN, DAT,  or PIC  file open, but you should be sure
     to consider  the consequences  of this before you do
     it:   If a  file is  open and  you change  disks  or
     delete the  file, you  may mess up DOS's idea of the
     current file  status', damaging  that file.   It  is
     advised  that  you  never  do  an  \EXECUTE  without
     closing all files unless you HAVE TO have them open,
     in which  case you  should try  not to  let the user
     have control  during the  \EXECUTEd operation.  Just
     do what  you have  to do, like an HPRASTER print for
     example,  and come back.

     During an \EXECUTE you can do anything that will fit
     in RAM,  including formatting  disks.   However  you
     should only  format diskettes  or execute Terminate,
     Stay Resident programs if absolutely necessary as it
     is likely to take some base RAM to do this, and that
     memory will NOT be returned until you reboot.
     When  executing   the  command  processor,  use  the
     command EXIT there to return to this program (either
     at the DOS prompt or from a batch file).

     DOS returns  a code  upon completion  of an executed
     program.   You will  find this code in variable "A".
     The executed program may return it's own code.  This
     will be  in variable "C".  Both these variables will
     be changed  by \EXECUTE.  If the  command fails  for
     some  reason   variable  "A"  will  contain  -1  and
     variable "C" will contain the error code returned by
     DOS.   Possible reasons  would be  disk errors, file
     not found, etc.



                       **** FRAME ****


FORMAT: \FRAME #,#,#,#{,M or O or OM or MO}  or \FRAME #
          or \FRAME ?


     Specifies that a frame should be added to the end of
     the current  picture file.   You must already have a
     picture file  in RAM or EMM.  This command will only
     add a  single frame at the end.  If you specify four
     numbers this  will add  a  raster  frame.    If  you
     specify just  one number  a  vector  frame  of  that
     number of dots will be added.  It will have "random"
     dot values  at the  start.  A question mark (?) will
     place the current total number of frames in variable
     "A".

     Specify four  numbers to get a raster image from the
     screen.   The first  two are  the upper  left  X,  Y
     location on  the  screen.    The  third  and  fourth
     numbers indicate  the  size  of  the  frame.    This
     command  will   round  the   first  value,   the  X-
     coordinate, down  to a  byte boundary.   In CGA mode
     there are  four dots  per byte so values of 0, 4, 8,
     12 etc.  would not  be changed  but 1, 2 and 3 would
     all be  rounded down,  having the  effect of  saving
     from the  zero position  on the  X-axis.  5, 6 and 7
     would all  round to  the fourth  dot position and so
     on.     The  right-hand   edge  will   be   adjusted
     accordingly so that the width will remain unchanged.
     See the \SCREEN command for a table of dots per byte
     for each available screen mode.

     ,M will  add a  masked frame,  while ,O  will add on
     onion skin  frame.   ,MO or  ,OM will  add a  masked
     onion skin frame.  Of course, onion skin mode is not
     available in monochrome modes!

     The base  location stored  in the  header of the new
     frame will  be 0,0  as will  the  base  time  value.
     Therefore,  you   will  need  to  use  the  location
     specified in the \FRAME command when you display the
     frame, for it to be in the same location.

     You can  save up  to a full screen--in CGA mode that
     would be  320 on  the X-axis  and 200 on the Y-axis.
     When testing a text file that contains this command,
     the command  will  add  a  frame  each  time  it  is
     encountered,  so  you  may  find  you  picture  file
     getting very big very quickly!
     If you  need to  allow more than the default maximum
     of about  1000 frames, use the P11FLAGS= environment
     string option or command line parameter:


               F:#          (where # is between 10 and
          8,000.)






                      **** HEIGHT ****


FORMAT: \HEIGHT #


     Specifies the height of a text window on the screen.
     Used with \LOCATE and \WIDTH to define the area text
     will appear  in.  Text can be \SCROLLed or \OVERLAYd
     in the  window you  define and  place with  \HEIGHT,
     \WIDTH and \LOCATE.  (\CRAWL does not use \HEIGHT.)



                        **** HUE ****


FORMAT: \HUE {COLOR=#,#} {SET=#,#,#} {INCREMENT=#,#,#}
          {HOLD={YES or NO}} {CY=YES or NO} GRAY={Y or N}


     Hues are  preset for  all colors, but on VGA systems
     you can  reset each  color to  a choice  of  262,144
     hues.   Each of  the three  portions of each color--
     red, green,  and blue,  can be set to numbers from 0
     to 63.

     By using  this command repeatedly in a text file you
     can do "color cycling."

     You can  set the internal hue table and not actually
     set the hue hardware registers by using HOLD=YES.

     INCREMENT= will  modify the  current hue values of a
     color.   The increment  values can each be positive,
     negative, or 0.

     The COLORS=  values  are  the  low  and  high  color
     numbers that are to be changed.

     CYCLES=YES does  color cycling.   It moves the color
     down 1  within the range and flips the bottom to the
     top.  Can be added to \RUN too.

     GRAY=YES the  colors are  changed but  NOT the color
     table.   To go back to non-grayscale, use \HUE C=#,#
     without any  other parameters.  If C=#,# is included
     with GRAY=Y, only those colors would be gray scaled.
     For gray scaling, S, I, and H are ignored.



                        **** IF ****


FORMAT: \IF # {=><} # {{AND or OR} # {=><} #}


     This command  is used to compare two operands or two
     sets of two operands.

     The expression  is evaluated  and if  true the \THEN
     clause  is   executed,  then  the  \ELSE  clause  is
     skipped.  If it evaluates to false the \THEN portion
     is skipped  and the \ELSE clause is executed.  These
     can be  nested 32  deep, and  should be  ended  with
     \ENDIF.

     If the  two #'s  represent numbers they are compared
     arithmetically.   If they  represent  auxboxes  with
     alphanumerics in  them they  are compared  as  ASCII
     strings with  the exception  that lower-case letters
     are capitalized  for the  comparison.   If  the  two
     strings are  of unequal  length the  shorter one  is
     "padded" with  spaces.   The ASCII value of a single
     character in  quote marks  (single or double) can be
     compared arithmetically.   You may use two operators
     together (<=,  <>, or  >=)  if  desired.    You  may
     connect two sets of comparisons together with either
     AND or  OR, but only one such connection can be made
     (only one  keyword AND  or OR  will be evaluated per
     \IF command).


EXAMPLE:

     \IF (A + 4) < B\THEN\IF #44 <= #54\THEN\MOVE 44 TO #87
     \ELSE\IF S <> 99 OR V=88\THEN\CALL LOOP1\ELSE
     \JUMP   LOOP2\ELSE\MOVE   "APPLES   AND   ORANGES"   to
     #989\ENDIF

     NOTE: the  THEN command  is always optional.  Spaces
     after the  backslash are  ignored and  can sometimes
     make program logic easier to follow.

     You may  want to  consult the section on programming
     and  the  \ELSE,  \THEN,  and  \ENDIF  commands  for
     further descriptions of "if" statements.



                        **** IN ****


FORMAT: \IN # {BYTE or WORD}


     IN will let you receive data from a hardware device,
     often called a PORT.  The byte or word input will be
     placed in  variable "A".   Generally, # is between 0
     and 255 and refers to a device in the system.



                     **** JOYSTICK ****


FORMAT: \JOY (or \JOYSTICK) {OFF, ?} {INITIALIZE
          {CENTERED=#,# RESOLUTION=#,# SAMPLES=#}} {ZERO}
          {ACCURACY=#,#}


     If INITIALIZE  is used,  the same  thing happens  as
     when you  press  <CTRL>+j  while  creating  drawings
     except values  for RESOLUTION, SAMPLES, and CENTERED
     are taken  from the  command and  not asked  of  the
     user.   A message  appears near  the bottom  of  the
     screen instructing  the user  to move  the  joystick
     around and  press a key.  These keypresses do NOT go
     into variable "B".

     The numbers  that the  joystick returns are products
     of the  current cursor  location  plus  values  that
     correspond to the joystick positions.

     \JOYSTICK ON  or \JOYSTICK  with no  parameters will
     get joystick information and if the joystick was off
     but had  been previously  initialed, will turn it on
     again.

     OFF will  inhibit use  of the  joystick but does not
     actually send any signal to the input device.

     A question  mark (?)  will put  the  status  of  the
     joystick in  variable "A".    Any  other  parameters
     would be ignored.  The status is as follows:

     1 - port assumed to be available, not on.
     2 - port used, so definitely available.
     3 - currently in use (active).

     Initializing the  joystick turns  off the  digitizer
     but not  the mouse  if on.  Use \MOUSE OFF if you do
     not want both on.

     RESOLUTION is the maximum variation from the current
     position  that  the  joystick  can  return  (maximum
     deflection by the user) and is a number from 0 to 50
     (0 means no movement on that axis.)

     SAMPLES are the number of times to read the joystick
     value that  is returned before automatically summing
     the numbers,  throwing out  the highest  and  lowest
     values, and  averaging the  rest.    Sampling  is  a
     number from 4 to 50.
     The Centered  option will cause the joystick to move
     the cursor  around the  point specified.  It will be
     able  to   move  the   distance  specified   in  the
     RESOLUTION= parameter.  In this mode deflection will
     always be from the centered point, not from the last
     value returned.

     ACCURACY is  the units  of variation.   For example,
     A=5,5 will  return values  of  -15,-10,-5,0,5,10,15,
     etc. within  RESOLUTION maximums  (plus and  minus.)
     The accuracy rounds towards 0 to a multiple of these
     settings.

     The joystick  will simply  invert  the  #'s  if  the
     joystick is held upside down and initialized, but if
     at a  90 degree angle, you will get an error message
     (Error Code 3585.)



                      **** JRCOLOR ****


FORMAT: \JRCOLOR #,#,#,#,#


     The IBM-PCjr,  as well  as most  TANDY (Radio Shack)
     PC-compatibles have  the ability to display any four
     of 16  colors in CGA mode.  To set these colors, use
     this command.

     Set the  background with  the first  value, then the
     three foreground colors.  The fifth value is for the
     border, which  can also  be set  to one  of  the  16
     available colors.

     On TANDY  machines you  may have  to execute the DOS
     command  MODE   with  the   option  COLORMAP  before
     executing this program for \JRCOLOR to work.



                       **** JUMP ****


FORMAT: \JUMP NNNNNN


     NNNNNN is  a named place in your text file.  See the
     \X command.   The  name can  be one  (1) to 30 bytes
     long  and   cannot  contain   spaces.    \JUMPs  are
     different from  \CALLs because  they do not retain a
     return address  (the address  of the command after a
     \CALL statement is saved for a corresponding \RETURN
     statement to  use.)   Jumps just  go  somewhere  and
     processing continues from there.  The usual thing to
     code after  a \JUMP  is an \X command for some other
     \JUMP, \CALL, \ON KEY or \ON ERROR command to go to,
     or if  the \JUMP  was within the \THEN portion of an
     \IF statement,  an \ELSE  or \ENDIF command may also
     follow a \JUMP.


Example:

     \* This  routine waits  forever for  ANY key  and  then
     displays it's value.
     \MOVE 0 TO B
     \X NO_KEY_PRESSED_YET
     \IF B=0
     \   JUMP NO_KEY_PRESSED_YET
     \ENDIF
     \DISPLAY B



                        **** KEY ****


FORMAT: \KEY CYCLE=# DECREASE=# END=# FORWARD=#
          INCREASE=# MINUS=# NEXT=# PLUS=# REVERSE=#
          SINGLES=#


     Lets you assign keyboard codes for various \SHOW and
     \RUN options.   The  numbers correspond  to DOS scan
     codes for various keypresses.

CYCLE=#
     Assigns a  key which will cause animation to stop at
     the end of the cycle.  Only used for \SHOW.

DECREASE=#
     Assigns a key for slowing down animation.

END=#
     Assigns an  alternate key for the ESC key.  Pressing
     the real  ESC key three times in a row will override
     this and  force the keycode anyway.  You cannot code
     the RET (return) keycode (7181) for this key.

FORWARD=#
     Assigns a  key for  single-stepping forward  through
     the frames.  Only used for \SHOW.

INCREASE=#
     Assigns a key for speeding up animation.

MINUS=#
     Assigns a  key for  making animation  run  backward.
     Only used for \SHOW.

NEXT=#
     Assigns a  key for ending animation and advancing to
     the next command.  Only used for \SHOW.

PLUS=#
     Assigns a  key for  making  animation  run  forward.
     Only used for \SHOW.

REVERSE=#
     Assigns a  key for single-stepping backwards through
     the frames.  Only used for \SHOW.

SINGLES=#
     Changes the  single-dot cursor  movement toggle key.
     Initially the  "5" key  on the numeric keypad serves
     this purpose  on XT-style  keyboards.   Setting this
     will toggle  it to  single-dot.   A value  of 0 will
     inhibit changing the dot travel distance.

     NOTE: +  and -  (plus  and  minus)  on  the  numeric
     keyboard are already assigned to PLUS= and MINUS=.

     For some  of  these  keys  we  recommend  using  the
     following keys:

                      DESCRIPTION                        KEY
    KEY VALUE

     CYCLE........SPACE BAR...................14624
     DECREASE.....DOWN ARROW..................20480
     FORWARD......RIGHT ARROW.................19712
     INCREASE.....UP ARROW....................18432
     NEXT.........RETURN KEY.................. 7181
     MINUS........MINUS KEY...................18989
     PLUS.........PLUS KEY....................20011
     REVERSE......LEFT ARROW..................19200
     SINGLES......"5" KEY ON KEYPAD (XT-STYLE)19456


     0 coded in any parameter turns off that option.

             NUM  LOCK  ON                    NUM  LOCK  OFF
    KEY VALUE

     PG DN........20787.......................20736
     PG UP........18745.......................18688
     HOME.........18231.......................18176
     END..........20273.......................20224
     LEFT ARROW...19252.......................19200
     RIGHT ARROW..19766.......................19712
     UP ARROW.....18488.......................18432
     DOWN ARROW...20530.......................20480




                      **** LENGTH ****


FORMAT: \LENGTH #


     Gets the  length of the specified auxbox and puts it
     in variable  "A".   Numeric auxboxes  are always two
     bytes long.  If the auxbox does not exist the length
     will be zero (0).


Example:

     \MOVE "EAT MORE CHILI!" TO #32
     \LENGTH #32
     \DISPLAY A      ;15 would be displayed
     \MOVE 324 TO #33
     \LENGTH #33
     \DISPLAY A    ;2 would be displayed



                       **** LINE ****


FORMAT: \LINE #,#,#,#,#{,B or ,BF} or \LINE ,#,#,#{,B or
          ,BF}


     Draws a line on the screen.

     The first  two numbers  are the  X, Y coordinates of
     one end of the line, the next two are the other end.
     The fifth  number is the color.  The second position
     given  will   become  the  "current"  endpoint  (see
     below).

     If you  use the second option (three values preceded
     by a  comma) a  line will  be drawn from the current
     endpoint (set  by a previous \LINE or \DRAW command)
     to the  endpoint given in the first two values.  The
     third value is the color.  The current endpoint will
     be updated to the new endpoint.

     ,B (comma  B) will  draw a rectangle with corners as
     specified, while  ,BF will  draw a  filled box.  The
     ,BF option will NOT be affected by the status of the
     XOR switch  nor will  it affect  that switch.    All
     other options  of \LINE  are affected by the current
     state of the XOR switch (set with \DOT).

     Some lines  are not clipped properly.  Specifically,
     if the  total separation  on either  axis of the two
     endpoints is  greater than  32767 and both endpoints
     are off  the screen  the displayed  line may  not be
     correct,  or  incorrect  lines  are  displayed  that
     should have  been completely  off the  screen.  This
     does not occur except on widely separated endpoints.
     These long lines are excessive values that cannot be
     coded in  vector draw  mode, and  are unlikely to be
     coded in  \LINE or  \DRAW commands.   But since it's
     documented, don't be surprised when--and if--it ever
     happens to  you.  Don't utilize it though--it may be
     inconsistent!



                       **** LOAD ****


FORMAT: \LOAD NNNNNNNN.PIC


     This works as a combination of \OPEN and \READ.  You
     can \READ  and \LOAD  at the  same time.  You CANNOT
     \OPEN and \LOAD at the same time.

     Load will  not decompress  the file, but nor will it
     use EMM.   So,  if you are working in base RAM, this
     can save  space, BUT, and this is a big but, it will
     only do the things \OPEN can do - it won't work with
     \RUN, only with \SHOW.



                      **** LOCATE ****


FORMAT: \LOCATE #,#


     #,# is  the X  and Y position for the text cursor to
     put text  lines, alphanumeric  auxboxes and literals
     on the  screen.   The X-axis  number may  be rounded
     down, because resolution is every byte on the X-axis
     and every  dot on  the Y-axis.   For example, in CGA
     mode there  are 4  dots per  byte on the X-axis.  In
     all bitplane modes, there are 8 dots per byte.



                      **** MARQUE ****


FORMAT: \MARQUE #,#,#,#{,#{,#}}


     This forms  a moving  multi-colored rectangle on the
     screen.   The first  four numbers are the X, Y upper
     left corner  and the  X, Y  lower right corner.  The
     fifth number  is the  number of colors to use in the
     marque.   If a  sixth number  is included,  then the
     fifth and  sixth numbers  are the  "from"  and  "to"
     numbers for  the marque.   The  marque  will  remain
     running on  the screen  until any  key is pressed or
     until the  value set  with \ROUNDS  is exceeded (see
     \ROUNDS).  Speed of each cycle is set with the SPEED
     option of  \ROUNDS.   If ROUNDS is exceeded, -1 will
     be in  variable "B",  otherwise the value of the key
     pressed will  be there.   A  mouse button press will
     also exit  this routine.  Variable "C" will have the
     number of completed cycles.

     A good  use of  this command  might be  to  indicate
     where the  user is  to enter  a response--it doesn't
     "absorb" the  keypress.   If the  very next  command
     were \QUESTION  coded  on  the  same  line  the  key
     pressed would  go into  that routine.   \MARQUE gets
     the key  value and  puts it in variable "B" but does
     not get the key from the keyboard.  Pressing a mouse
     button would  simply exit  the \MARQUE  command  and
     enter the next command.


EXAMPLES:

     \MARQUE 20,27,44,78,2 \QUESTION #33

     The above  example would  give the  keypress (if one
     occurred before  either the  time ran out or a mouse
     button was  pressed) to  \QUESTION because  they are
     coded on the same line.

     \MARQUE 11,13,99,122,3
     \QUESTION W

     The above  example would NOT give the key that ended
     \MARQUE to \QUESTION.



                      **** MEMORY ****


FORMAT: \MEMORY {?} {EMM}


     Places the  size of the largest piece of memory left
     for  pictures,   executing  subprograms,   etc.   in
     variable "A".   This  does not include space used by
     any pictures  already in RAM, so it is indicative of
     space left  to  \APPEND  frames  with.    The  value
     returned is  in K  (1024 bytes).   The question mark
     (?) is optional.

     If the second option, EMM, is used, this will return
     the total  number of  NEVER-USED  16K  (16384  byte)
     pages that  have been  allocated to the program.  It
     is NOT  necessarily the  available  amount,  but  is
     certainly  less   than  or   equal  to   the  amount
     available.   When pages  of EMM  are  taken  by  the
     program, they  are not  returned until  exiting  the
     program.   Therefore, for  example, if you read in a
     very large  picture  file  and  then  a  very  small
     picture file,  the number  of pages returned by this
     function will  be quite  a bit  less  than  what  is
     actually available  at the  time, since once you had
     read in  the large  file, the amount never used will
     be less.



                       **** MOUSE ****


FORMAT: \MOUSE {INITIALIZE, OFF, or ?} {AND={YES or NO}
          ACCURACY=#,# END=#,#,#,# FRAME=#,# KEEP=Y (or
          anything for no) LOCATION=#,# OR={YES or NO}
          RESOLUTION=#,# ROUNDS=# SPEED=# WINDOW=#,#,#,#
          XOR={YES or NO or AUTOMATIC}}


     \MOUSE allows  input  of  the  cursor  location  and
     buttons pressed  from the  active input  device, and
     displays a cursor (either a frame, or crosshairs, or
     both) at  the current  position. Raster  frames,  if
     used as  a cursor,  are positioned with their center
     on the current cursor position.

     \MOUSE executes  until  exited  by  one  of  several
     methods.   To exit,  the timer can run out (which is
     set with  the ROUNDS=  option);   the user can press
     any mouse button;  they can press any active \ON KEY
     key; they  can enter  any active END window; or they
     can press RETURN.

     The user can use the cursor keys and the number keys
     to  move  the  cursor.  The  joystick,  keyboard  or
     digitizer  can   be  substituted   for  the   mouse.
     (Hardware limitations do not allow the digitizer and
     the cursor  keys to both work at the same time.)  To
     some extent,  the joystick and the mouse may be used
     together.

     If you  want the  user to  use the mouse buttons (or
     RETURN) to end the mouse activity then don't set any
     END= parameters  after a  \CLEAR MOUSE  command.  If
     you want  action to  end the  moment  they  enter  a
     "forbidden zone" (or zones) then END is the choice.

     You may  not need to know how the \MOUSE command was
     exited, but  that can  be discerned by examining the
     appropriate variables.   Variable  "F" will  contain
     the input  device button  value that  was pressed if
     that is  how the routine was exited, or it will have
     zero  and  variable  "B"  will  have  the  last  key
     pressed.   If variable  "F" is zero and variable "B"
     is unchanged from a non-valid key value that you had
     previously set  it to,  AND variable  "C"  indicates
     that ROUNDS=  had not  completed, then  the end MUST
     have been due to the mouse entering an "END" window.
     In any  case "D"  and "E" will have the mouse X- and
     Y- axis positions.
INITIALIZE
     INITIALIZE can  only be  used if  no editing changes
     exist  to  any  files  in  RAM,  or  the  mouse  has
     previously been  initialized.   However,  since  the
     program  initializes  the  mouse  immediately  after
     loading, this  problem  should  never  occur.    The
     reason the  program will  not let you initialize the
     mouse if  changes exist is that if mouse software is
     not installed you may have to "reboot" if you try to
     initialize the  mouse!   This in  not  very  likely,
     perhaps not  even possible,  but there is no way for
     the program  to be  absolutely sure.    The  program
     checks for  a valid  (non-zero)  address  where  the
     mouse software address should be.  If it's non-zero,
     the program "dips it's toe in the water" and sends a
     request to the mouse.  See Appendix "K" and Appendix
     "N" for more information.

?
     ? (Question mark) will put the current status of the
     mouse in variable "A".  The meanings are as follows:

     0 -  mouse software definitely not installed yet, can't
     initialize.
     1 - can initialize, but are not connected yet.
     2 - mouse is already initialized.


     NOTE:
     ? sends a reset message to initialize the MOUSE.
     IF  THAT   SOFTWARE  IS  NOT  INSTALLED,  THE  PROBLEMS
     MENTIONED EARLIER MAY OCCUR.
OFF
     Will turn the mouse off if it is on.



     The other  options can  be entered in any order. For
     any that  are not included the previous settings are
     maintained.

AND=YES or NO
     AND will place the image on the screen with AND.  It
     will leave  a trail.   \CLEAR  MOUSE sets  AND to NO
     (off).

ACCURACY=#,#
     Sets the  X and  Y accuracy  in dots.    Useful when
     block-highlighting text.   To do this, set the mouse
     WINDOW= parameter width to 1 dot and the height to a
     multiple of  the text font height.  Set ACCURACY= to
     the text  font height.   Make  a frame  the  inverse
     color of the text you will use, the size of the text
     box to  be highlighted  and use it as a cursor.  Use
     the XOR=AUTOMATIC  option.  You could make a grid of
     text boxes this way too.  \CLEAR MOUSE sets ACCURACY
     to 1,1.   The  ACCURACY= calculations are done as if
     the starting  location was  0,0 then  the  X  and  Y
     offsets are added to get the "actual" current cursor
     location.

COLOR=#
     Allows  you   to  set   the  color   of  the  cursor
     crosshairs.   Valid colors in CGA mode are 1, 2 or 3
     (not 0).   In MCGA mode the highest color values are
     not available  (above 247).   In  all  modes,  color
     cannot be 0.

END=#,#,#,#
     This defines  a  window  that  will  end  the  mouse
     routine if  the mouse  ever enters it.  You may have
     up to  10 active END windows. \CLEAR MOUSE sets this
     to 0  (no end-windows).    Order  is  X-low,  Y-low,
     X-high, Y-high.   These  parameters are  not checked
     against each  other for  equivalency, so  don't code
     the same  one 11  times--you'll get  a CAN'T PROCEED
     error the  11th time.   To  avoid this, issue \CLEAR
     MOUSE prior to setting up the END parameters.

FRAME=#,#
     The  first   value  sets  the  size  of  the  cursor
     crosshairs and  the second value sets a frame to use
     as a  cursor.  If both are zero the cursor will be a
     single dot,  but if  the frame # is not zero and the
     crosshair value  is zero,  then  there  will  be  no
     crosshair. \CLEAR MOUSE sets this to 4,0.

KEEP=Y or anything else
     Only useful  if XOR=AUTO.   Leaves  the  last  frame
     (and/or crosshair)  on the  screen  when  \MOUSE  is
     exited (regardless of what causes the exit).

LOCATION=#,#
     This option  sets  the  starting  location  for  the
     mouse.   If not included, the position is decided by
     the current mouse location if the mouse is active or
     by  the  location  set  by  \DOT  or  several  other
     commands.

OR=YES or NO
     OR will  place the  image on the screen with OR.  It
     will leave  a trail.   \CLEAR  MOUSE sets  OR to  NO
     (off).

RESOLUTION=#,#
     Is the  maximum variation  from the current position
     that can  occur per  cycle.    First  value  is  the
     minimum change  and the  second value is the maximum
     change.  \CLEAR MOUSE sets RESOLUTION to 1,-1.

ROUNDS=#
     Sets an  upper limit  for how long the mouse will be
     active.   The number  of rounds  executed will be in
     variable "C"  at the  end.   A round is defined as a
     new location or one cycle, initially about 1/20th of
     a second.   If  you set  this value  to -1 the mouse
     will run  forever  unless  one  of  the  other  exit
     methods occurs.   \CLEAR  MOUSE sets this to -1.  If
     you set  it to  0  the  mouse  cursor  will  not  be
     displayed or used at all.

SPEED=#
     Sets the timing for each ROUND.  Initially it is set
     to 29, which is about 20 cycles per second.  At that
     rate  the   number  of   ROUNDS  divided  by  20  is
     approximately equal  to the  number of  seconds that
     the mouse  will be  active.  Zero (0) here means "as
     fast  as  possible".    Program  updates  the  mouse
     location once  per cycle.   \CLEAR MOUSE resets this
     to 29.   This  is the  speed  of  the  screen  image
     update.

WINDOW=#,#,#,#
     This sets  maximum and minimum values for the cursor
     in the  form X-low,  Y-low,  X-high,  Y-high.    The
     cursor will  appear whole  even if  parts of  it are
     outside of  this window but the cursor location will
     stay within  these values  (inclusive).    By  using
     narrow values  for one  of the axis you can make the
     cursor move  only up  and down  or back  and  forth,
     useful for choosing menu options.  \CLEAR MOUSE sets
     this to the full screen.

XOR=YES, NO, or AUTOMATIC
     The frame used as a cursor can be permanently placed
     at every  point it  touches if so desired (NO) or it
     can be  automatically XOR'ed  onto  the  screen  and
     XOR'ed off  again when moved (AUTO).  It can also be
     set to  be XORed  onto the  screen but not XORed off
     (YES).   The  crosshair  is  not  affected  by  this
     option--it is  always removed.   Set  to auto-xor by
     \CLEAR MOUSE.


EXAMPLES:

     \MOUSE INIT
     \MOUSE R=4444 W=33,44,104,199 L=12,13
     \MOUSE ROUNDS=44 WINDOW=0,22,319,23
     \MOUSE R=-1 A=10,1 W=33,10,33,190
     (The last  example would  run forever  until one of the
     exit methods discussed above is taken).



                       **** MOVE ****


FORMAT: \MOVE #{[#,#]} TO #


     The first  # can  be a  literal in  single or double
     quotes.   The #  after TO  can be  a variable  or an
     auxbox.   Of course  if it's  a variable the first #
     has to  be numeric  data.   This command creates the
     auxbox if it has not been created yet and changes it
     to  numeric   or  alphanumeric   as  needed.     The
     destination  auxbox will always become the same type
     as the  source.   You can move variables to auxboxes
     and you can move auxboxes to variables if the auxbox
     is numeric.

     You can  move a portion of an alphanumeric auxbox by
     immediately following the auxbox name or number with
     brackets and  two values  separated by  commas.  The
     values are  the starting  position within the source
     auxbox and the length in characters to move.

     If  the   starting  string   is  shorter   than  the
     "destination" as  defined by  your offset and length
     values, it will pad with spaces.

     When moving  a literal  (in single  or double  quote
     marks) to  an  auxbox  the  maximum  length  of  the
     literal itself is 254 characters.




EXAMPLES:

     \MOVE 343 TO W
     \MOVE TIME&DATE[1,8] TO #32
     \MOVE "Hi! " TO #1



                     **** MULTIPLY ****


FORMAT: \MULTIPLY # BY #


     Both values  must be numeric.  The second number can
     be an  expression that  evaluates to a value and the
     result goes  in the  first value,  which must  be  a
     variable or auxbox.

EXAMPLES:
     MULTIPLY G BY 23
     MULTIPLY W BY (#33 * 22)-44+(X*Y*Z)



                       **** NAME ****


FORMAT: \NAME # = NNNNNNNN


     Defines a  symbolic name  which can  then be used to
     refer to an auxbox, instead of using its number.

     NNNNNNNN is  a  name  that  starts  with  three  (3)
     capital letters and is at least three (3) characters
     long.   It ends  with a  capital  letter  and  is  a
     maximum of  30   characters. It  cannot contain  any
     spaces.   The only  other legal  characters are  the
     numbers 0  through 9,  the  ampersand  (&)  and  the
     underline (_).   Each auxbox can have no name or one
     symbolic name,  and a  name can  refer to  only  one
     auxbox.   \NAME does  NOT establish the existence of
     an auxbox,  only its  name.  Use \MOVE to create the
     auxbox.   The name  TIME&DATE is already assigned to
     auxbox #32767.   All other names can be cleared with
     \CLEAR NAMES.


EXAMPLE:

     \NAME #2346=SAVE_THE_PLANET
     \MOVE "YES" TO SAVE_THE_PLANET



                     **** ON ERROR ****

FORMAT: \ON ERROR [JUMP or CALL or CALLM]  NNNNN
FORMAT 2: \ON ERROR

     This will  do  a  jump  or  call  to  the  paragraph
     specified as  NNNNNN if  any error occurs other than
     those listed as SEVERE errors (see below.)  The line
     number where  the error occurred will be in variable
     "A".  To get the actual error code that occurred (or
     the last  one if  multiple errors  occurred  on  the
     line) use \ERROR.  If nothing is specified after \ON
     ERROR then  error trapping is turned off (format 2).
     Error trapping  is a  one-shot: once used, it is set
     off until  another \ON ERROR jump or call is issued.
     Therefore if an error occurs, you must issue another
     \ON ERROR  command to inhibit any errors again.  You
     may want  to do  this  in  the  error  trap  routine
     itself.

     IMPORTANT NOTE: Some errors, documented elsewhere in
     this manual, indicate that a reboot may be necessary
     after they  occur.   Although these errors SHOULD be
     impossible to get, it is noted here for completeness
     that the  controlled recovery  capabilities of  this
     command may  not work  in these  cases.  All efforts
     have been  made to  make the  program "bulletproof",
     that is,  it should  not be  possible to  crash your
     computer while  using this program.  However despite
     all the effort this may not be the case!

     The active screen will be the real screen (screen 0)
     after ANY error, even if it was trapped.

     The real  purpose of this command is not so that you
     can always  restart but  rather it  is to  provide a
     mechanism  to  handle  things  like  file-not-found,
     disk-full and so on.

     Errors  in   the  runtime  version  that  cannot  be
     restarted  (whose   SEVERITY  LEVEL   is  too  high)
     include:

     3562 & 3563 (wrong screen mode errors.)

     32767 & 32765 (load errors.)

     Both these  errors can only occur during the initial
     program load,  before  any  files  have  been  read.
     Other  errors   that  cannot  be  restarted  involve
     attempting to  change .i.screen modes; while picture
     files for other modes exist in RAM or EMM.

     The following  additional errors  are severe because
     they would  result in overlaying edit changes.  They
     can only occur in the editor version:

     5, 7, 525, 2624, 4522 & 9218.

     And these  errors are  also severe, and indicate you
     wrote your program with syntax errors:

     4 and 4004. (paragraph names not found.)



                      **** ON KEY ****

FORMAT 1: \ON KEY= {YES or NO}
     Sets the program to jump to the second command of
     a text  file.    Format  is  an  equal  sign  (=)
     followed by YES or NO.

FORMAT 2: \ON KEY F# {{JUMP or CALL or CALLM} NNNNNN}
     This  format  sets  \ON  KEY  specifications  for
     function key  values.    Code  an  F  immediately
     followed by  a number  1 thru  10 (NOT  something
     that evaluates  to a  number, an  actual  number)
     with no space.  Follow with CALL or JUMP and then
     a  paragraph   name  (NNNNNN)   to  set  \ON  KEY
     processing.  Use just the function number to shut
     off a previously set \ON KEY specification.

FORMAT 3: \ON KEY # {{JUMP or CALL or CALLM} NNNNNN}
     \ON KEY # {JUMP, CALL or CALLM} NNNNNN where # is
     the decimal  value of  a  key  and  NNNNNN  is  a
     paragraph name  to jump  to or call when that key
     is pressed.   Leave  the name blank after the key
     value to  turn off  the specification.    Fifteen
     (15) individual  key specifications can be active
     at one time, plus function key specifications.


\ON KEY=YES
     Means any keypress (except ESCAPE) will cause a jump
     to the  second command of the text file. It will NOT
     jump to  the second  line of the command file unless
     the first  line has only one command.  =NO turns off
     this function.   You  will find  the  key  value  in
     variable "B".



     ON KEYs  are used to control branching within a text
     file based on user input.  An ON KEY command remains
     in affect until it is set off (or a new text file is
     read in.)   A maximum of 15 specific keys (format 3)
     plus 10  function keys  (format 2) can be set at one
     time.

     An important fact to keep in mind when using \ON KEY
     is that  all \CALL,  \CALLM, and \IF nesting is lost
     with execution  of an  \ON KEY  JUMP but NOT when an
     \ON KEY  CALL occurs.   An \ON KEY...JUMP works just
     like a  \JUMP  command  but  occurs  when  the  user
     presses the appropriate key, while an \ON KEY...CALL
     behaves like a \CALL or \CALLM command.
     There are  only two  ways to get back to a text file
     after an  \ON KEY jump into a macro file.  You could
     have coded  an \ON  KEY in  the text file that would
     still be  active, or you could issue a \READ command
     to read  a text  file and  processing will go to the
     start of  the text file.  Other than these two ways,
     you will be stuck in macros forever.

     It is possible to code values which do not represent
     any possible  keypress.   You can code a value which
     represents ESCAPE  to the  program (283)  but if the
     user presses that key three times in a row an escape
     option WILL  BE PROCESSED.  You can use \PASSWORD to
     prevent unauthorized exiting.

     The global  \ON KEY  specification (format 1) is NOT
     ACTIVE during  \QUESTION.   All other  \ON KEY's are
     checked with  each key  the user presses.  If an \ON
     KEY jump occurs while the user is editing a line the
     line is  accepted as is and then the \ON KEY process
     occurs.   Global \ON KEYs are also not active during
     "single-step" (debugging)  mode.  If both global and
     specific \ON  KEYs are  active the specific \ON KEYs
     take precedence.

     ON KEY...CALL's  exit the  current command  or  text
     line and will not reenter \MARQUE, \SHOW, \MOUSE and
     \RUN.   \RETURN will be to the command following the
     current command.  If you changed fonts and locations
     and so  on in  the \ON KEY called routine these will
     remain as  changed.  Paragraphs that are called with
     \ON KEY...CALL  should IMMEDIATELY  turn off the \ON
     KEY condition  that called them, on the same line as
     the paragraph name (or on a line connected with a \+
     command).   Otherwise if  pressed again it will "re-
     call" the  paragraph!   Just before  the \RETURN (on
     the same  or a  connected line)  turn  the  \ON  KEY
     condition on again.  Since \ON KEY's are NOT checked
     after  a   \RETURN  command   this  will  mean  that
     processing will  have a  chance  to  return  to  the
     original  calling  area  before  doing  another  \ON
     KEY...CALL.   In general, \ON KEY...JUMP's are quite
     a bit  simpler to  use and  are recommended whenever
     possible.

     Using \ON  KEY #  CALL NNNNN  can result  in a CAN'T
     PROCEED error  code 3  (Too many  calls), especially
     if taken  via a  mouse or  other user  input  device
     button.   This is because the program checks for the
     pressing of  the button  very rapidly;  it can do it
     many times  before the button is released.  To avoid
     this, turn  OFF the  \ON KEY CALL (\ON KEY # will do
     it) as  soon as  you get to the called paragraph (on
     the same  line as the paragraph name or connected to
     it with  a \+ command.)  Also be sure to connect the
     line that  turns \ON  KEY back  on with  the \RETURN
     that matches  the call.   Or, have the entire called
     paragraph be connected with \+ commands.

     ON KEY's  are checked once between each command line
     in the text file.  For text lines, once between each
     row or  column placed  on the  screen.   The  actual
     number of checks that will occur per text line would
     depend on the height or width of the font.  Checking
     will NOT occur between multiple commands on the same
     line,  except   prior  to  \"  commands.    You  can
     temporarily "inhibit"  \ON KEY  checking  by  coding
     commands on  the same line.  This can be significant
     help in insuring that several processes all occur if
     the first one occurs.  It also executes faster.  You
     can inhibit  \ON KEY  checking between command lines
     if the last command on the previous line is \+.  See
     that command  for more  information on  it's use and
     restrictions.   \ON KEY's are always checked after a
     \JUMP has occurred.


EXAMPLES:

     \ON KEY=YES
     \ON KEY F8    ;Turns off a specification for F8.
     \ON KEY #3071 JUMP BEGIN

     \ON KEY 16424 CALL SPACE_BAR_PRESSED
     \ON KEY F3 JUMP SOME_PLACE_NICE
     \ON KEY 7181 ;Turns off \ON KEY for the RETURN key.

     \ON KEY 7181 JUMP UP_AND_DOWN



                       **** OPEN ****


FORMAT: \OPEN {NNNNNNNN.PIC} {NNNNNNNN.DAT} {NNNNNNNN.PRN
          {ADD}} {LPT1:} {LPT2:} {LPT3:} {LPT?:} {IGNORE}


     Use NNNNNNNN.PIC to open disk-based animation files.
     These are  animation sequences  for use by the \SHOW
     command.  It is a way to animate sequences of frames
     that  are   larger  (perhaps   much  larger!)   than
     available RAM  or EMM.   File should be closed after
     use.

     Use NNNNNNNN.DAT  to open  text-style data files for
     use with  the \DATA  command.  File should be closed
     after use.

     For print  files (output  ASCII  files),  \OPEN  can
     specify either  a disk  file (extension PRN), or the
     system printer; LPT1, LPT2, or LPT3, or any printer,
     LPT?.   Either LPT#,  or a print file MUST be opened
     before any  \PRINT statements  attempt to  write  to
     them.  You can use the option IGNORE after the LPT#:
     to ignore  the  return  code--the  printer  will  be
     considered opened  regardless  of  what  the  status
     value is.   We  recommend you DO NOT use this option
     without advising the user explicitly that the system
     could hang  if the program tries to access a printer
     that is not available.

     You can  only have  one print  file open  at a time.
     Use the \CLOSE statement to close them.  A disk file
     may be  reopened after  being closed, for additional
     \PRINT statements to use, by using the ADD option of
     \OPEN.  The "file pointer" will be at the end of the
     file, of course.

     Any CAN'T  PROCEED errors  in processing  will cause
     print, data,  and disk-based  animation files and/or
     LPT1, LPT2,  or LPT3  to be closed.  Opening a print
     file will  destroy an  old one  on the disk with the
     same name  unless you use the ADD option, so only do
     this with  files you  want this  to happen to!  When
     you open  LPT1, LPT2,  LPT3, or LPT? a reset code is
     sent  through  the  BIOS  to  the  printer  and  the
     printer's return  status code  is placed in variable
     "A".  The meaning of this code is documented in BIOS
     technical references.  The program  will wait  up to
     about 12  seconds for  the printer to return a valid
     (not busy) code.
     Picture files shown with \OPEN can use significantly
     less RAM since they use only the decompress area and
     take no additional RAM or EMM of their own.

     Note: Any  \ON KEY jumps leave the opened file open,
     so have the jumps go to places that close the opened
     files or  don't use \ON KEY jumps with \OPEN, or set
     it up so it expects files to be opened, or store the
     status of  the file  and  behave  accordingly.    Or
     something...



                        **** OUT ****


FORMAT: \OUT #,# {BYTE or WORD}


     The first  value is  the port, usually 0 to 255, and
     the second  value is  the amount  to be \OUTed.  The
     second value  can be  \OUTed at the address given in
     the first  value as  a byte  or word,  depending  or
     which parameter  you use.   As  a byte  it  must  be
     between 0 and 255 and as a word, -32K to +32K.



     To use  this command,  you MUST  know what  you  are
     doing!   This can  directly affect  the hardware  of
     your system  and even cause damage to your system or
     that of  your users!   You  could  actually  harm  a
     monitor, disk  drive,  or  other  device  with  this
     command!   Of course,  you are  much more  likely to
     just  need   to  reboot   if  you   use  it  without
     understanding it, but...   DON'T USE \OUT UNLESS YOU
     UNDERSTAND WHAT IT DOES.

     Therefore, you  must use  \AUTHORITY HIGH  to enable
     this command.

     Do not,  REPEAT DO  NOT use  this command unless you
     are absolutely  sure that you understand the purpose
     of ports,  hardware devices,  the ASSEMBLER LANGUAGE
     OUT command (which this executes), and anything else
     that might be important, depending on which port you
     plan to OUT data to!

     And don't  come crying  to us  if you  disobey these
     cautions and  ruin your  system!   THIS  COMMAND  IS
     DANGEROUS DON'T  USE  IT  WITHOUT  UNDERSTANDING  IT
     FIRST.





                      **** OVERLAY ****


FORMAT: \OVERLAY #{,X or O or A}


     Sets the text display mode to OVERLAY (as opposed to
     SCROLL or  CRAWL).  The number is the speed at which
     to overlay  text.   If a  question mark (?) is used,
     text mode  is changed  to overlay  and  the  current
     speed is  placed in variable "A".  IF ,X is included
     the text  is XORed  onto the screen, if ,A ANDed, if
     ,O ORed.

     AND, OR,  and XOR are most useful for fonts designed
     with just black (background) and the highest numeric
     color available for the screen mode.

     In bitplane  modes you  can AND,  OR, and  XOR  with
     color 1  only.   Use  TEXT  PLANE=  to  get  similar
     effects to what this would have given with XOR, AND,
     and OR in bitmapped modes.



                       **** PAINT ****


FORMAT: \PAINT #,{UDLRVHBA}


     The #  specifies the  border color  to paint  up to.
     The program will paint in the current color (perhaps
     set with  \DOT until  it reaches  the border.    The
     UDLRVHBA indicates  in which direction to paint (up,
     down,  left,   right,  vertical,   horizontal,  both
     (vertical and horizontal) and all).  Painting occurs
     from the  current position.   When called from \DRAW
     just the  P should  be used  (not the  AINT).    The
     option  Small   Square,  available  in  the  picture
     editor, is not available as a command.

     Painting will  take place  in the  current color set
     with \LINE,  \DOT, \DRAW,  etc..   Except for option
     "A" \PAINT  will remain  active  until  turned  off.
     Only one  direction can  be used  at a time.  \PAINT
     without any parameters turns OFF paint mode.

     For the  "A" option,  the next dot drawn acts as the
     "seed" and painting occurs within an area bounded by
     the border color specified or the paint color.  This
     option shuts  off after  one use.   This option uses
     the same  storage area  that "tilt" (in the editor's
     draw mode)  uses, so  if you want to use a tilt line
     repeatedly, do  NOT paint  in between  uses.    (See
     tilt.)

     The paint  "all" option utilizes a temporary storage
     area in RAM to accomplish it's task.  It is possible
     to use  up this  area in a very "complex" paint job.
     If this  happens, some  areas will  not  get  filled
     completely.  The position of the original "seed" can
     have some  effect on  the result  in this  case.  If
     this is  a problem,  try to  divide the  area to  be
     painted into  two or  more  individual  sections  to
     paint.



                     **** PASSWORD ****


FORMAT: \PASSWORD EXIT=# {or "NNNN" or 'NNNN'}  TIME=#


     This allows you to control runtime user's ability to
     return to DOS from within an application.

     The maximum  password length  in  single  or  double
     quotes is  10 characters.  It may be an alphanumeric
     auxbox or  literal in  quotes but  NOT a variable or
     numeric auxbox.   A  password of  a space  or spaces
     clears the option.

     Password checking  occurs  when  ESCAPE  (or  a  key
     assigned to  ESCAPE) is pressed.  The full length is
     taken even if a wrong key is pressed.  Passwords are
     only used  in  the  runtime  version.    The  editor
     version will parse the command but will not actually
     set up a password protection scheme.

     Time is  specified in  584ths (approx.)  of a second
     units.   The minimum  value of  118 is equivalent to
     about 1/5th second.  Time is per character.

     Return  must   be  pressed  after  the  password  is
     entered.



                        **** PEN ****


FORMAT: \PEN {AIRBRUSH={NO or #{,#,#...}}} {COLOR=#}
          {WIDTH=#} {XOR={YES, NO, ON, OFF}} {CYCLE={NO
          or #{,#,#...}}}


     Sets pen options for \DOT, \DRAW, \LINE and \CIRCLE.

AIRBRUSH=NO or #{,#,#...}
     Turns airbrush  mode on  or off for subsequent \DOT,
     \DRAW, \LINE  and \CIRCLE  commands. Strength of the
     spray is set with the WIDTH option.  You can specify
     up to  ten different  colors and  these override the
     COLOR option  (see below).   Use  NO to turn off the
     airbrush.

COLOR=#
     Sets pen color for subsequent \DOT, \DRAW, \LINE and
     \CIRCLE commands.   Valid  options are 0 through the
     maximum color  for the  screen mode (3 in CGA mode).
     Use any  negative number  for clear.   No value will
     also evaluate to clear, but only if this is the last
     option in  the command.   (Otherwise the keyword for
     the next option will be evaluated as the number!)

CYCLE=NO or #{,#,#...}
     Turns color  cycle mode  on or  off  for  subsequent
     \DOT, \DRAW,  \LINE and  \CIRCLE commands.   You can
     specify up  to ten different colors.  Use NO to turn
     off the  color cycle  option.   Since C= would set a
     color, you  must type  at least  the CY=  portion of
     this parameter.

WIDTH=#
     Sets pen  size for subsequent \DOT, \DRAW, \LINE and
     \CIRCLE commands.  Valid options are 1 through 5.

XOR=YES or NO, ON or OFF, AND, OR, XOR
     Sets XOR,  AND, or  OR   on or  off  for  subsequent
     \DRAW, \LINE  and \CIRCLE  commands.   \DOT  is  not
     affected by this command's XOR setting.  Through the
     current release  7.24, XOR  is not  compatible  with
     wide pen  lines.   Only a  one-dot wide line will be
     drawn properly  in XOR  mode.  YES/ON and NO/OFF are
     exactly equivalent.



                       **** PRINT ****


FORMAT: \PRINT #{,#,#,#...}


     Writes to  a print  file or  LPT#:.   You must first
     \OPEN the file or use \OPEN to initialize the system
     printer.

     The format  of \PRINT's  parameters work  just  like
     \DISPLAY, except  you may  specify numeric values to
     print with  brackets ([#]).   If you have a trailing
     comma    the     program    will     NOT    add    a
     carriage-return/line-feed after  whatever you print,
     but if  the comma is not there, then it WILL add the
     CR and LF characters (13,10).  Numeric values except
     those in brackets ([ ]) are converted to a string of
     ASCII characters  and then  the  string  is  printed
     Those inside of brackets are sent as 1-byte unsigned
     numbers and cannot be less than zero or greater than
     255.

     If you have not opened LPT#: \PRINT writes to a disk
     file previously  \OPENed and  does not  write to the
     printer.   It will actually write the record to disk
     whenever 512 bytes have been printed.  When the file
     is closed the rest, if any, is written.

     One way to print this file later might be to issue a
     command to  do so  from DOS with \EXECUTE.  You must
     close the disk file before you do this.


EXAMPLES:

     \PRINT [27],'  Prints the escape character, which has a
     decimal value  of 27,  and  then  prints  this  message
     followed by a cr/lf.'
     \PRINT #232,TIME&DATE," HAVE A NICE DAY",

     The second example would print whatever is in auxbox
     #232 immediately  followed by  the TIME&DATE auxbox,
     followed by  the phrase HAVE A NICE DAY which starts
     with a  space.   No cr/lf is added since the command
     ends with a comma.



                     **** QUESTION ****

     FORMAT: \QUESTION #,#{,#{,LOWER}}

     Gets keyboard  input from  the user and places their
     response in a variable or auxbox.

     If the  value of  the second  number is 0, this asks
     for a  number from  the user  and puts it's value in
     the location  mentioned in  the first  number, which
     must be an auxbox or variable.  Otherwise it gets an
     ASCII string  of the  length specified by the second
     number (1  thru  80)  and  puts  it  in  the  auxbox
     specified by  the  first  number.    If  the  auxbox
     already contains alphanumeric data its contents will
     appear in  the user's  edit window  for them to make
     additional changes  to.    The  user's  edit  window
     location is  set with  the \CURSOR  command.   \WAIT
     LIMIT sets  how long,  in seconds, this command will
     wait for  user input.   The  user exits \QUESTION by
     pressing the  RETURN key or any mouse button (unless
     the button  has been reassigned to a different key.)
     \QUESTION uses the DOS standard font for user input,
     and  the  actual  screen.    It  will  not  use  the
     background screen.

     The third  parameter is the cursor position when the
     routine begins.   If not specified it will be on the
     first character in the line.  After getting numerics
     the cursor will be advanced seven positions.  If you
     specified a  text window  with \CURSOR  #,#,#,# then
     the line  will  be  kept  inside  that  window  with
     automatic scrolling  if necessary.    After  getting
     alphanumerics the cursor position will be set to the
     beginning of the line.

     When entering  alphanumerics users  can  only  enter
     capitalized letters  unless LOWER has been specified
     as the  fourth parameter.   The third parameter must
     be included to use this fourth parameter.

     Numeric data  outside the  valid  range  (-32768  to
     +32767)  will   be  forced  into  the  valid  range.
     Numbers entered  which are  less than -32768 will be
     returned as  -32768, and  numbers greater than 32767
     will become  32767.. In  both instances, the speaker
     will beep  if the  sound is  not toggled  off.  When
     getting numeric  data, this  will blank  the six (6)
     characters forward from (to the left of) the current
     cursor position FIRST.



                       **** READ ****


FORMAT: \READ {drive:}{/path/}NNNNNNNN.EXT


     Reads  a   picture,  font,   text,  macro,  hue,  or
     auxiliary file into RAM or EMM.

     The  filename  (NNNNNNNN)  can  be  proceeded  by  a
     numeric literal, variable or auxbox and a colon (:).
     This will  force a  new  default  drive.    You  are
     probably used  to referring  to the  drives as  "A",
     "B", and  "C".   Within this  program use  numbers--
     Drive "A" is 1, "B" is 2, etc.
      You may optionally include a path specification,
          this will  change the  default path.   Since
          the  program  uses  the  backslash  (\)  for
          commands  you  cannot  use  that  slash  for
          pathnames in command lines!  Use the forward
          slash (/) for pathnames instead.


      EXT determines most of what this command does:


      TXT will  read in  a new  text  file  and  start
          executing  that  file  from  the  beginning.
          Your previous  text file  is overlaid.  (You
          cannot overlay  edit  changes,  of  course.)
          Any \ON  KEY specifications that were active
          for  text   will  be  eliminated  when  this
          command is  executed, but  NOT any macro \ON
          KEY specifications.


      FON will  read a  font file  into the font area,
          overlaying any  previous font.   It will NOT
          move the  font into  the picture area.  This
          can only be done manually.  The font area is
          normally 20K  bytes, but  can be  set before
          loading P11  to any  value from  3K  to  63K
          bytes with  a  parameter  in  the  P11FLAGS=
          environment string (or on the command line).
          To do so, use:


               FONT:#        (# is from 3 to 63)


      HUE will  read a  hue file  into the  hue  table
          area, overlaying  any hue  information  that
          was  already  there    (you  cannot  overlay
          changes in  the editor.)   Each  screen mode
          has it's  own hue  table where  the hue data
          will go.   You  should only  read a HUE file
          for the mode you are in.


      AUX will  read an  auxiliary file  into the  aux
          area overlaying any auxfile that was already
          there.


      PIC reads  a picture  file providing  no changes
          were made  to the  current one.  The picture
          will be  read into RAM, or EMM if available.
          The number  of frames  read in  will  be  in
          variable "A"  after this option is executed.
          If the  picture is  in a different mode from
          the current  one the  screen  mode  will  be
          changed to  the new picture mode.  EMM usage
          can be  disabled or  limited by  setting the
          P11FLAGS= environment  string or the command
          line parameter:


               EMM:#         (0 to inhibit EMM, or any
          desired # of EMM pages.)


      MAC reads a macro file if the name is not one of
          the nine  (maximum) stored names.  Reading a
          macro does  NOT clear \ON KEY specifications
          for other  macros.  \CLEAR MACROS will.  All
          paragraph names  in all  macros in memory at
          any  one  time  must  be  different  or  the
          program will  only access  the first  one it
          encounters.   This will  not necessarily  be
          the first  one in  the file.   It may be the
          closest, the  first, the  next,  etc.    The
          easiest way  to insure  that the proper name
          is found  is to give all the paragraph names
          in each macro a unique prefix.

     You may  specify the drive as a variable, number, or
     numeric auxbox.    You  can  specify  the  path  and
     filename (with  the extension)  as auxboxes too.  To
     do this,  put the  auxbox in  parenthesis.  The path
     must  ALSO  be  within  slashes  (NOT  backslashes).
     Within  the   auxboxes,  put   the  period  and  the
     extension with  the filename  (example:  HORSE.TXT).
     Within the pathname auxbox include slashes (forward-
     or back-slashes  are okay within auxboxes).  You may
     use a  single auxbox  which includes drive, path and
     filename.

     NOTE:   These commands  will only  read the file off
     the disk if the file is not already in RAM.


EXAMPLES:

     \READ #3:/(#4)/(#5)
     \READ 3:/FROG/(#6)
     \READ /FROG/PIG.PIC
     \READ (#7)

     In the  first example  all three  elements--drive, path
     and filename with extension--are specified symbolically
     through the  use of  auxboxes.  In the next example the
     path and drive are "hardcoded" and the filename.ext are
     in auxbox  #6.   In the third example the current drive

     is used  and the path and filename are "hardcoded".  In
     the last  example auxbox  #7  may  contain  the  entire
     drive, path  and filename, or the path and filename, or
     the drive  and filename, or just the filename.  Current
     values will be used for unspecified elements.



                      **** RESTORE ****


FORMAT: \RESTORE {SCREEN}


     The entire  screen can  be stored  in  a  background
     area.   This will get a screen previously saved with
     \SAVE SCREEN.   The background area is the same area
     used by the raster frame mask option.

     You can also restore the screen from disk by setting
     B:0 in   environment  variable P11FLAGS=  or on  the
     command line.   This will cause the entire screen to
     be read  from a  file called SCRNDUMP.SV# (#=1 or 2)
     in the directory \P11\TEMP.





                      **** RETURN ****


FORMAT: \RETURN


     Will cause  processing  to  return  to  the  command
     immediately after  the last  call.   A call  can  be
     established with  \CALL, \CALLM,  \ON KEY...CALL  or
     \ON ERROR...CALL.  The place returned to could be in
     the midst  of an  \IF  statement,  but  the  \RETURN
     itself  cannot  be  between  an  \IF  statement  and
     \ENDIF.   No \ON  KEY  processing  or  input  device
     checking occurs  between a  \RETURN command  and the
     next command.



                      **** ROTATE ****


FORMAT: \ROTATE {ANGLE=# FRAME=# LOCATION=#,#}


     Lets you rotate a vector frame anywhere from 0 to 90
     degrees.  The parameters can appear in any order and
     should be separated by at least one space.  Location
     refers to  the center  dot location  about which the
     rotation should  take place.  The location  must  be
     between -2000  and +2000  inclusive  on  each  axis.
     Angle is degrees of clockwise rotation.



                      **** ROUNDS ****


FORMAT: \ROUNDS # {SPEED # or [#{,REPEAT}] {FIXED}
          {REVERSIBLE} {WAVING}} {RANGE #,#} {RETRACE}


     Sets the  number of  cycles that  \MARQUE, \SHOW  or
     \RUN will  execute.   SPEED refers  to the  time for
     each cycle.   Each  unit represents a small fraction
     (about 1/584th)  of a second.  The larger the number
     the longer the pause.  If a question mark appears in
     SPEED or  RUN, the  current value  will be placed in
     variable "A".  When the program starts ROUNDS is set
     to -1  (cycle forever), and SPEED is set to [0] (use
     frame speed controls).

     If the  speed value  is enclosed  in brackets  ([ ])
     then the  frame number  specified will  be  used  to
     control the  speed.   If non-0, frame must be in RAM
     or EMM:  it cannot  be part of a disk-based picture.
     This must be a vector frame.  The Y-axis values will
     be the  timing units  for each frame.  The first and
     last dots  will not be used.  If the frame number is
     followed by  the word  REPEAT then the cycle will be
     repeated.   Otherwise the  last value  will be  used
     repeatedly after  cycling through the frame once.  A
     value of  0 in  brackets ([0])  will  use  the  base
     timing values  for each  frame   This is the default
     when the  program starts.   Base timing values of -1
     will wait for a keypress or mouse press.

     The following additional words may be included after
     the SPEED parameter.  They do not affect \MARQUE.

FIXED (F)
     When specified  the user CANNOT change the animation
     speed with  the up and down arrow keys (or any other
     keys  that  might  have  been  set  with  the  \KEYs
     command.)  The default is not FIXED.

REVERSIBLE (R)
     Allows  the  user  to  reverse  any  animation  that
     following \SHOW  commands  display  (not  used  with
     \RUN).  To do this they must press "-" (minus).  "+"
     (plus) makes  animation run  forward again.    These
     keys may  be reassigned  with \KEY.   The default is
     not REVERSIBLE.

WAVING (W)
     Used with  \SHOW.   Animation goes  from  the  first
     frame to  the last  and then back down again a frame
     at a time.  The default is NOT waving.

RANGE (RA)
     The user  can speed  the animation  up to as fast as
     the first  number and  as slow as the second number.
     The defaults  are 0  (as fast  as possible)  and  -1
     (stopped).  Whatever you set these to will remain in
     effect until the next \ROUNDS command, where it will
     be set  to the  defaults unless  reset by you.  Note
     that a  "wrong" initial  value for SPEED in terms of
     being OUTSIDE  the max/min  speeds in RANGE will NOT
     be checked  - but the first time speed is CHANGED by
     the user - POOF! it must fit in the boundaries!



RETRACE (RET)
     For \SHOW, this will start placing each frame on the
     screen at  the START  of the  next vertical  retrace
     period.   This MIGHT  make some  bitplane animations
     smoother.   The default  is NOT paying any attention
     to retrace timing.



                        **** RUN ****


FORMAT: \RUN {FROM #} {TEXT} {MOUSE}  {HUES} {NUMBERS or
          FACTS {#}}


     Runs animation  sequences set  up with  \SPRITE  and
     \SPRINT for \ROUNDS number of cycles unless an exit,
     such as  an \ON  KEY keypress, occurs.  The user can
     adjust the  speed if the FIXED option of \ROUNDS has
     not been issued.

     FROM #  causes the \ROUNDS cycle counter to start at
     the  value  specified  rather  than  at  zero.    No
     actions, such  as string or position increments etc.
     prior to  that cycle  will take  place.   The  cycle
     counter  counts  up  until  it  reaches  the  number
     specified in \ROUNDS.

     With each  cycle of  \RUN animation,  vector  images
     with \SPRITE  XOR=AUTO will XOR off the previous one
     before XORing  on the new frame.  With raster images
     it does these two operations concurrently.
      HUES     will execute  the previous HUES command
          once with  each cycle.  This is for use with
          CY=YES in the \HUES command.


      MOUSE will  execute a  previous  \MOUSE  command
          concurrent with  the sprite  activity.   The
          ROUNDS= and  SPEED= options  of  \MOUSE  are
          ignored in  this case.   This  lets a  mouse
          cursor be  moved around  on the  screen with
          the \RUN  animation, but  can leave  unusual
          pieces of  images  on  the  screen  in  some
          cases.


      TEXT will  cause lines  of text  to be displayed
          concurrently.   The lines to be shown follow
          \RUN in the text file, and will be placed on
          the screen  according to  the  current  text
          display  mode.     If   a  command  line  is
          encountered the  text display  will stop and
          the \RUN  command will  finish it's  cycles.
          If on  the other hand the \RUN cycles finish
          first, the  text line  display will complete
          before going  on to  the next  text line  or
          command.

     The number  of cycles  completed will be in variable
     "C" when  this command  is exited  regardless of how
     the exit  occurred (finished, \ON KEY pressed, etc.)
     Through the  current release,  if  more  than  32767
     rounds have  passed negative  numbers will  be used,
     counting up from -32768.

     NUMBERS and  FACTS are debugging aids available only
     in the editor version.  If either is included with a
     FROM parameter, FROM must be coded first.

NUMBERS will display five numbers on the bottom of the
     screen.   The first  is the  \SPRINT number being
     shown.   The second number is the frame number in
     the picture file.  The next number is the current
     round, and  the last  two numbers are the current
     position of the sprite.


FACTS displays  the current  values for sprite motion.
     It shows  two number  columns and  one  character
     column.    The top line on the screen is the same
     as that  displayed by  the NUMBERS  option at the
     bottom of  the screen.   See  Appendix "A"  for a
     complete listing  of what  each value  refers to.
     Press Pg  Dn to  show more  numbers for  the same
     frame and  HOME to go back to the first screen of

     information.   Use the  left and right arrow keys
     to see  other sprite  values without advancing to
     the next  frame.   Press any other key to advance
     to the  next frame.   \ON KEY jumps and calls are
     partially inhibited  in this  mode.  You may have
     to press  the key  repeatedly or  hold it down to
     get it to "take".

     FACTS and  NUMBERS can  be followed  by at least one
     space and  a number.   If present then facts/numbers
     will not  be displayed  until after  that round  has
     occurred.   If left in a RUNTIME version, these must
     be the  last parameters  on the  line  and  will  be
     ignored.  It is better to remove them after use.


EXAMPLES:

     \RUN FROM 23 NUMBERS 44
     \RUN MOUSE FACTS
     \RUN
     \RUN TEXT MOUSE FROM 23 NUMBERS 30



                       **** SAVE ****


FORMAT: \SAVE {SCREEN}


     The entire  screen can  be copied to its own storage
     area.  The screen can then be restored with \RESTORE
     SCREEN.   This uses  the same  area that is used for
     raster pictures with masks.

     You can  also save  the screen  to disk by using the
     option B:0  in the environment variable P11FLAGS= or
     on the  command line.   This  will cause  the entire
     screen to  be "dumped" to a file called SCRNDUMP.SV#
     (#=1  or  2)  in  the  directory  \P11\TEMP.    This
     directory MUST  exist to  use this option!  The disk
     name will  end in  either a  1 or  a 2.    \EXCHANGE
     SCREEN will  toggle the  name since  it first writes
     out a new screen dump, then reads the old one.



                      **** SCREEN ****


FORMAT \SCREEN #,#{,#} or MODE=# or ?


     The first number is the background color, the second
     is the palette, and the third number, if present, is
     the screen mode.  The default screen mode is 4, CGA.
     If the  parameter form is used, only the mode number
     is changed.   Since only CGA uses the background and
     palette values,  MODE=# is  sufficient for all other
     modes.   Note:   Do NOT use  the MODE= option in the
     environmental variables  or on the command line.  It
     is not able to parse that option.  Use the three #'s
     version instead.

     If a  question mark  (?) is used the current mode is
     placed in variable "A".

     This command  can  be  entered  from  the  P11FLAGS=
     environment string  or from  the  command  line,  in
     brackets.   If it  is found  there, the mode will be
     set before any files are read in.  In the editor you
     can use  this option  to  convert  images  from  one
     screen mode to another.  Enter the mode you want the
     picture to  end up  as in the environment string and
     then read the picture file into the editor.

               SCREEN:#,#,#


     In CGA  there are  two palettes,  0 and  1,  and  16
     background colors,  0 through  15.   Background  and
     palette values  are passed to DOS, which changes the
     screen.

     If the  screen mode  is  actually  changed  by  this
     command, \CLEAR  MOUSE and  \CLEAR SHOW commands are
     executed automatically.   It  is a  good idea to re-
     initialize  the  digitizer  if  it  is  being  used,
     because the  dimensions may  not match  the  current
     screen mode.

     Valid modes are:

Screen        Dot
Character
Mode   Dimensions  Colors   Dots/byte   Dimensions
Comments
    4.......320 X 200.4..4.....40 X 24   CGA-the
original P11 mode.
    5.......320 X 200.4..4.....40 X 24   CGA, but a
different palette.
    6.......640 X 200.2..8.....80 X 24   CGA monochrome
mode.
    9.......320 X 200.16.2.....40 X 24   PCjr or TECMAR
depending on hardware.
   10.......640 X 200.4..4.....80 X 24   TECMAR 4-color
mode.
   13.......320 X 200.16.2.....40 X 24   EGA 16-color
low-res mode.
   14.......640 X 200.16.2.....80 X 24   TECMAR 16-color
mode.
   16.......640 X 350.16.8.....80 X 24   EGA 16-color
high-res mode.
   17.......640 X 480.2..8.....80 X 30   MCGA high-
density monochrome mode.
   18.......640 X 480.16.8.....80 X 24   VGA 16-color
mode.
   19.......320 X 200.2561.....40 X 24   MCGA rainbow
mode.


     NOTE 1: With third party software, mode 4 can be run in
     monochrome on HERCULES hardware.

     NOTE 2:  PCjr modes  are also  called extended  CGA and
     available from many TANDY machines.



                      **** SCROLL ****


FORMAT: \SCROLL #{,{AOX},#}


     Similar to  \OVERLAY and  \CRAWL but  sets the  text
     display mode  to scroll all text up the screen.  The
     first parameter  sets the  speed of the scroll.  The
     second parameter, if included, will cause text to be
     XOR'ed, AND'ed, or OR'ed with the color specified in
     the third parameter before it appears on the screen.
     Unlike \OVERLAY  this will  not XOR, AND, or OR with
     what is already on the screen--that gets scrolled up
     and lost.

     AND, OR,  and XOR are most useful for fonts designed
     with just black (background) and the highest numeric
     color available for the screen mode.

     As with  \CRAWL and  \OVERLAY in bitplane modes, you
     can only  XOR, AND,  or OR  text with  color 1.  Use
     TEXT PLANES= to get additional colors.



                        **** SET ****


FORMAT: \SET COLOR=# DOT={# or ?} FRAME=# LOCATION=#,#
          MODE={GET or SET}


     Lets you  manipulate individual  dots  of  a  vector
     drawing from  within a  command file.   COLOR is the
     dot's new  color.   DOT is the dot number.  FRAME is
     the frame  number the  dot belongs  in.  LOCATION is
     the new  X-axis and Y-axis values for the dot.  MODE
     lets you choose to GET information about the current
     dot's location  and color,  or SET  it.  (SET is the
     default.   If GET  is used  it must be specified for
     EACH \SET command.)

     IF the  DOT=? option  is used, then the MODE= option
     will be  ignored, the current dot will be set to dot
     1 (the  first dot  in the file) and the total number
     of dots  in frame  specified in  the FRAME=#  option
     will be  placed in  variable "A".   The vector image
     will NOT be changed at all.  If you use this command
     on a RASTER image it results in an error.

     This command  does not  create a  frame or insert or
     delete  dots.    It  only  changes  dots  within  an
     existing frame.   Use  \FRAME  to  create  a  vector
     frame.   You cannot  execute this command if changes
     exist to the picture file currently in memory.

     You can let values default.  Any value not specified
     will default to the value in a previous \SET, except
     DOT will increment by 1 if not specified explicitly.



                       **** SHOW ****


FORMAT 1: \SHOW #,#,#,#{,A}{,O}{,X}{,S}



FORMAT 2: \SHOW  AND={YES or NO} FRAME=#,# LOCATE=#,#
          MOTION=#,# OR={YES or NO} PATH=#{,#} SAVE={YES
          or NO} WINDOW=#,#,#,# XOR={YES or NO}


     Does animation  on the  screen, saves  a frame whose
     space has already been allocated, or AND's, OR's, or
     XOR's a  frame onto the screen.  For raster drawings
     accuracy is  to the  nearest byte  boundary  on  the
     horizontal axis.  In CGA  mode it is every 4 dots, 8
     dots in  monochrome modes,  etc.   See \SCREEN for a
     table of  dots per  byte.    For vector drawings the
     location specified  is NOT offset by the first dot's
     value.   If a  disk-based animation  file  is  open,
     \SHOW will  use it,  but any  vector paths or timing
     frames must be in RAM or EMM.

     In format  1, the  first two values set the location
     on the  screen.   The next values are the "from" and
     "to" frames,  and the  fifth value  if present  is A
     (and), O  (or), X  (xor) or S (save).  These options
     are valid  only when  the "from" and "to" frames are
     the same.   See  the descriptions  in  format  2  to
     understand how each of these options function.

     If you  just want  to show  one frame  on the screen
     without AND,  OR, or  XOR you  can  just  use  three
     numbers  (the  X  and  Y  locations  and  the  frame
     number).

     In format 2, parameters are specified with keywords.
     Their meanings follow:

AND={YES or NO}
     When placing  only one  frame on  the  screen  (both
     FRAME= values  are the  same) you may use AND.  This
     is a  mathematical function  which ANDs  the picture
     into the screen.

FRAME=#,#
     Indicates the  "from" and "to" frames, respectively,
     to animate.   If  the second number is less than the
     first, the  animation  will  run  in  reverse  order
     unless the  second number  is  -1,  which  means  to
     animate all frames from the first number to the last
     frame in the file.

LOCATE=#,#
     The upper  left corner of the animation.  For raster
     frames  add  the  base  offset  to  get  the  actual
     location, rounded to a byte boundary.  (In CGA mode,
     every 4 dots.)

MOTION=#,#
     Indicates X-  and Y-axis increments to the beginning
     location.  Incrementing occurs each cycle.

OR={YES or NO}
     When placing  only one  frame on  the  screen  (both
     FRAME= values are the same) you may use OR.  This is
     a mathematical function which will OR the frame into
     the screen.

PATH=#,# or PATH=NO
     Indicates a  vector frame  to use  as a  path.   The
     second #  indicates a  dot to  start at.   Use NO to
     specify no  path.   This will  repeat from the first
     active dot  (the second dot of the frame) if it gets
     to the penultimate dot of the frame.

SAVE={YES or NO}
     Saves rather  than displays a frame.  Only one frame
     can be saved at a time: FRAME=#,# must indicate only
     one frame--both  numbers must  be the  same.  If the
     frame dimensions  and the location specified cause a
     portion to  be outside  the screen  or  the  current
     window, only  that portion  visible would  be saved.
     The frame must already exist in the file.  This will
     overwrite it but will not be considered a change for
     editing purposes.   It  will not  execute if changes
     exist.

WINDOW=#,#,#,#
     Indicates a viewing window.  Lower X-axis values are
     rounded to byte boundaries.

XOR={YES or NO}
     When placing  only one  frame on  the  screen  (both
     FRAME= values  are the  same) you may use XOR.  This
     is a  mathematical function which will XOR the frame
     with the screen.  If you XOR the same image into the
     screen twice  in the same place, the original screen
     image will be unchanged.


Animation runs  for \ROUNDS number of cycles unless the user
exits by  pressing an  active \ON KEY or the \KEY NEXT= key.
A parameter  of \ROUNDS sets the speed.  The user can change
the speed  if the  FIXED option  of \ROUNDS  was not issued.
When exited  the number  of  cycles  completed  will  be  in
variable "C".


EXAMPLES:

     \SHOW 22,88,3,3,X
     \SHOW 37,45,4,8

     Parameters 1 and 2 are screen position.
     Parameter 3 is the beginning frame.
     Parameter 4  is the  ending frame.   This should be the
     same as parameter 3 for the ,A ,O, ,X and ,S options.
     Parameter 5,  if included,  is either  A for AND, O for
     OR, X for XOR or S for SAVE.


     \SHOW FRAME=7,-1 MOTION=4,0

     This example  uses the  keyword format  of \SHOW.    It
     would animate  from frame  seven through the last frame
     in the file.  These frames would move to the right four
     dots for each frame shown.



                       **** SOUND ****


FORMAT: \SOUND ON or OFF


     Toggles the  sound capabilities  on and off. It does
     not produce  any noise  but will  inhibit  \BEEP  if
     \SOUND is  set OFF.  If you  execute \SOUND  OFF all
     beeps will be inhibited including any you issue with
     \BEEP and any the program would issue itself.



                      **** SPRINT ****


FORMAT \SPRINT #{,# TO #...}


     Indicates the  frames to be used with current sprite
     motion parameters.  First, set up the desired motion
     parameters with \SPRITE.  Then indicate which frames
     should follow  those parameters with \SPRINT.  After
     you have  set up  all the  images with  their motion
     parameters,  use   \RUN  to  display  the  animation
     sequence.

     The word  SPRINT was  chosen because  the command is
     similar to  \PRINT in  syntax,  and  because  SPRITE
     characters can be made to SPRINT across the screen.

     To "sprint" animation you must list each frame to be
     sprinted or  use "  TO "  to indicate  a  series  of
     frames.


EXAMPLES:

     \SPRITE TYPE=R ANIMATE=3
     \SPRINT 1,2,3,4,5,6,7
     \RUN

     \SPRITE T=R A=3\SPRINT 1 TO 7\RUN

     \SPRITE T=R A=3 \MOVE 1 TO G
     \X LOOP1
     \SPRINT G
     \IF G<7 \ADD 1 TO G \JUMP LOOP1
     \ENDIF
     \RUN

     (These three examples produce the exact same image.)



                      **** SPRITE ****


FORMAT: \SPRITE AND=YES or NO ANIMATE={# or NO}
          CONNECT={YES or NO} INCREMENT=#,# END=#,#,#,#
          FAST={Y or anything} MOTION=#,# OPEN=#,#,#,#
          TYPE={R or anything} PATH={#,# or NO}
          ROUNDS=#,# STRING=#,# WINDOW=#,#,#,# WPATH={#,#
          or NO} XOR={N, A or Y} ZING={#,#,# or NO}


     Sets up  animation parameters  for \SPRINT frames to
     use.

     The keywords  are used  to control a wide variety of
     animation  activities.    After  using  \SPRITE  and
     \SPRINT commands  to set  up the  action use \RUN to
     activate  everything.    Motion  will  continue  for
     \ROUNDS number of cycles at a chosen SPEED.

EXAMPLE:

\SPRITE WINDOW=33,22,37,145 ROUNDS=33,76

     Would set  a display  window that would apply to any
     frames  that   are  set   with  subsequent   \SPRINT
     commands.   This would  change if  you issue another
     window value  or a \CLEAR SPRITES command.  It would
     also  set   the  elements  to  become  "active"  (be
     displayed if  in the  window) at round 33 and become
     inactive after round 76.



     Following are  the keywords (which can be entered as
     just  the   first  letter   or  letters)  and  their
     meanings:

AND=YES or NO
     The image  can be  ANDed, ORed,  or XORed  onto  the
     screen.  This will cause it to be ANDed.

ANIMATE=# or NO
     The value is the number of cycles to hold each frame
     on  the  screen.    Sometimes  you  do  not  want  a
     particular group  of animated  frames to  change  as
     frequently as other action occurs within a cycle, in
     that case  you would  use a  number greater  than  1
     here.   NO sets  this option  off.  Animation frames
     must follow one another with no intervening elements
     when created  with  \SPRINT.    Other  elements  can
     appear but each animation sequence must run together
     and be  separated from  other animation  by at least
     one non-animated  \SPRINT frame.   Only  one of  the
     frames in the sequence is shown per cycle.

     If the animation reaches a END= window or the end of
     a PATH, then if TYPE is not REPEAT but KEEP=YES, the
     animation will continue in place at the end location
     until the  ROUNDS= ending  cycle is reached.  MOTION
     amounts are  added  only  when  an  element  of  the
     animation sequence  is  displayed,  NOT  necessarily
     every round  (it depends  on the  value ANIMATION is
     set to.)  \CLEAR SPRITES sets animation to OFF (NO).

CONNECT=YES or NO
     This turns  on the  connected dot  mode  for  vector
     images.   Line segments  are drawn between each dot:
     the first  dot is drawn and subsequent line segments
     are the  color of  their endpoint. Their startpoints
     (the previous  line  segment's  endpoints)  are  not
     redrawn.   The lines  are clipped to the screen edge
     then the  individual dots  are drawn  or  not  drawn
     depending on  whether  they  are  within  an  active
     window.

END=#,#,#,#
     If the  sprite reaches  the window  defined by these
     four values  the sprite  action ends.    Values  are
     X-low, Y-low,  X-high, Y-high.   (The  actual  value
     stored is  offset by  the values in the first dot of
     the frame  (if vector)  or 0,0  (if  raster).)    If
     TYPE=R the sprite repeats in place if it gets to the
     END window.  The END= window is initialized to 5000,
     5000, 4999,  4999 by \CLEAR SPRITES, which indicates
     NO end area.

FAST=YES or NO
     This only  affects raster drawings.  When set to YES
     (or "Y")  images are  placed on  the screen  at byte
     boundaries for much faster operation.  Auto-xor will
     be treated  as XOR=YES  if FAST=YES.   FAST  must be
     equal to  YES to  use a  frame mask.   The  mask  is
     automatically ANDed and the image ORed together with
     the  background   screen  and   the  combined  image
     displayed on the screen.  Use this to move an object
     across a background image.

INCREMENT=#,#
     When using  the STRING= option for displaying vector
     frames these  values will  be added to the beginning
     and ending string values each round.  They represent
     the number  of bytes  to add.   Since each dot takes
     four bytes  in memory  a  value  of  four  (4)  will
     increment by  one dot  each cycle.   This  allows an
     increment of  less  than  one  dot  per  cycle,  for
     instance a  value of  1 will  increment by  one  dot
     every  four   cycles  while  a  value  of  two  will
     increment by  one dot  every other  cycle.    \CLEAR
     SPRITES sets this to 0,0.

KEEP=Y or anything else
     When  the   sprite  reaches  an  end  of  some  sort
     (location, round, etc.) it will NOT be xor'ed off if
     this is  set to Yes, even if Auto-xor is on.  If the
     sprite is  part of an animation sequence (ANIMATE=#)
     then the  animation will  continue  to  run  at  the
     stopped location until the ending round.  If the end
     was achieved  by reaching  the end  of a  path or an
     END=  window,   animation  at  the  ending  location
     continues.   (If  TYPE=REPEAT  then  animation  will
     continue at  the starting  location or  at the first
     dot of  a path.)   If  not animating, this option is
     only useful for auto-xor.

LOCATION=#,#
     This sets  the starting  location.  The first dot in
     the  image   (if  vector)  or  0,0  (if  raster)  is
     subtracted from  this value  and then all subsequent
     dots (if vector) are offset by the resultant amount.
     For raster  images, add  the base  offset to get the
     actual location.  Set to 0,0 by \CLEAR SPRITES.

MOTION=#,#
     This sets  up values  to be  added to the location X
     and Y  values each round.  (If animating, each cycle
     that an  image is changed).  With this option things
     can move  in any  direction including onto, off, and
     around the screen.  \CLEAR SPRITES sets this to 0,0.

OPEN=#,#,#,#
     This lets  you  adjust  the  corners  of  a  viewing
     window; the four values are the X-low, Y-low, X-high
     and Y-high  amounts to add to the base window values
     each time  the frame  is shown.  You may want to use
     negative numbers  for the  X-low and Y-low increment
     amounts and  positive numbers  of the  X-high and Y-
     high increment  amounts.  If any value becomes below
     0 or  greater than  the screen size it will cease to
     change.   If you  use a  window path  (WPATH=)  this
     option will not be utilized.  \CLEAR SPRITES sets it
     to 0,0,0,0.

OR=YES or NO
     The image  can be  ANDed, ORed,  or XORed  onto  the
     screen.  This will cause it to be ORed.

PATH=#,# or NO
     This indicates  a vector  frame to use as a path (or
     "track").   If the frame is raster it will be caught
     as an  error when  you use \SPRINT.  The first value
     is which  frame to  use as a path.  The second value
     is which  dot within  that path to start on.  If you
     choose the  REPEAT option of TYPE=, repetition along
     the path  will be  from the  beginning, NOT from the
     specified dot.   Repeat  begins when  you reach  the
     second-to-last dot  in the  path frame  or  an  END=
     window.   The second  value is  ONLY valid  for  the
     first time  around the  path.  The starting location
     will be  the sum  of the  values  in  the  LOCATION=
     parameters,  the   current  path   dot  chosen   and
     additionally, if  vector, the first dot (the one NOT
     shown) of the frame (NOT of the path).  To start the
     path at  the first  active dot (the second dot) of a
     vector image  code a one (1) in the second parameter
     of this option.  To turn off this parameter code the
     word NO  after the  equal sign.  \CLEAR SPRITES sets
     this option off.

ROUNDS=#,#
     Sets the starting and ending cycles that a sprite is
     to be shown from and until, respectively.  No string
     incrementing, motion,  etc.  will  occur  until  the
     starting round and the image will not be shown. Once
     the starting round is passed values will be adjusted
     once each  round based  on the options that were set
     with other  \SPRITE keywords.   Each  \SPRINT  frame
     will be  adjusted unless the frame becomes inactive.
     \CLEAR SPRITES  sets ROUNDS  to 0,-1.   -1  will run
     forever.   If the  -1 round  is reached  it will  be
     ignored and the sprite will continue to be active.

STRING=#,#
     This is  only useful for vector drawings.  It is the
     dots (not  including the  first and  last) that  are
     actually to be shown on the screen.  The first value
     is the  first dot  to show  and the  second  is  the
     number of dots to show.  If these values are changed
     with INCREMENT=  and reach  the next-to-last dot the
     string that  is shown  will work it's way completely
     off the  screen unless TYPE=REPEAT.  In that case it
     will repeat  from the  first active dot in the image
     for  a   length  specified,  NOT  from  the  initial
     starting dot.   That  dot is  only effective for the
     first pass.  The first active dot (the second actual
     dot) is  number 1.   \CLEAR  SPRITES  sets  this  to
     0,16384.

TYPE={R or anything else}
     Sets up  repeat-sequences.   Repeat  resets  to  the
     beginning values  and starts  over if  the  sprinted
     frame gets to the position given in END=. If a PATH=
     or STRING=  option gets  to the  last active  dot it
     will reset  to the  first active  dot.    Repetition
     stops if  the ending  ROUNDS= value is reached.  Any
     character except R sets this option off.

WINDOW=#,#,#,#
     Sets a  window smaller than full screen size. Images
     will scroll  out of  these windows  as if  they were
     scrolling off  the screen.   Window  is reset to the
     full screen size with \CLEAR SPRITES.

WPATH=#,# or NO
     Sets a path for a window to follow.  If you use this
     option the WINDOW= values will be the base (initial)
     window location and it's size.  You cannot use OPEN=
     with WPATH.  \CLEAR SPRITES sets this to NO.

XOR={A, N, X or Y}
     When set  to "N" (NO), objects are simply put on the
     screen where you say to.  If moving, they will leave
     a trail  unless the edges are the same color as what
     they move  across--experimentation will explain this
     better.   When set  to "A"  (Automatic) the  program
     will XOR  off the last position as it is drawing the
     new position.  This has the useful effect of leaving
     the background  image unchanged.   When  set to  "Y"
     (Yes) or  "X" the  drawing will be XOR'ed on, but if
     you want  to remove  it YOU  must XOR the frame onto
     the screen  a second  time.   XOR=NO is the fastest.
     \CLEAR SPRITES sets this to NO.

     You can't  mix vector and raster XOR=A animation and
     get what  you might  expect.  Animation in this mode
     can be  very useful--images  are removed  as the new
     ones are put on.  If you were to manually XOR frames
     on and  off they  will not  be  XORed  concurrently.
     Auto-xor works  fine for  all-vector  or  all-raster
     groups,  but  if  you  mix  types  in  an  animation
     sequence it  will XOR  off one frame THEN XOR on the
     next in AUTO mode.

ZING=#,#,# or ZING=NO
     The third  value here  sets a  raster frame  to  the
     location specified  by the  first two  values.   The
     frame's base  values are  added to the X- and Y-axis
     values specified to determine the actual location of
     the upper left corner of the image.

     This does  not by  itself  cause  the  frame  to  be
     displayed--yet.   When a  subsequent vector frame is
     passed over  the raster  frame, the  raster frame is
     displayed rather  than the  vector dots.  Works with
     XOR but not with AUTO-XOR.  ZING works with the FAST
     option to  display a  byte  at  a  time  (four  dots
     horizontally in CGA mode.)


EXAMPLES:

     \READ GALLOP.PIC\ROUNDS 50 SPEED 33\CLEAR SPRITES
     \SPRITE M=0,4 F=Y A=1\SPRINT 1 TO 15\RUN

     This would  make a  horse gallop across the screen from
     left to right.



                     **** SUBTRACT ****


FORMAT: \SUBTRACT # FROM #


     The first  value can be an expression that evaluates
     to a  number.   The answer  will be  placed  in  the
     second value.   The  first value  can be  a  number,
     variable or auxbox but the second must be a variable
     or auxbox.  Both values must be numeric.

     Remember that  the maximum  and minimum  values of a
     number or  32767 and  -32768 respectively,  and that
     results  of   mathematical  operations   will  "wrap
     around"  in   order  to   stay  within  this  range.
     Internal calculations are double-word signed values,
     accurate to 31 bits.


EXAMPLES:

     \SUBTRACT A FROM B
     \SUBTRACT 99 FROM #767
     \SUBTRACT (W-55) FROM Q



                       **** THEN ****


FORMAT: \THEN


     Follows an \IF statement and begins the portion that
     will be  executed when  the  condition  in  the  \IF
     statement evaluates  as true.   The \ELSE statement,
     which can  follow  the  \THEN  clause,  starts  that
     portion that  will be  executed if the \IF statement
     proves false.    Both  the  \THEN  statement  itself
     and/or any accompanying commands to execute, or text
     to display,  are optional.   In  that case you would
     code the  \ELSE portion  directly following  the \IF
     statement.   The \THEN statement doesn't actually do
     anything and  is totally  ignored, even if it is out
     of position,  but it can sometimes make your program
     a little easier to read.


EXAMPLES:

     \IF APPLES=ORANGES
     \THEN
     \    MOVE "OH MY GOSH!!" TO #21
     \ELSE
     \    IF PIGS_HAVE_WINGS = "TRUE"
     \    THEN
     \        MOVE "NO WAY!!" TO #21
     \    ELSE
     \        MOVE "ALL IS WELL" TO #21
     \ENDIF
     \DISPLAY #21

     In this  example APPLES,  ORANGES, and  PIGS_HAVE_WINGS
     are all named auxboxes.



                       **** TEXT ****


FORMAT: \TEXT {PLANES=1111}


     PLANES=is a binary number.  It is only applicable to
     bitplane modes  and should contain as many digits as
     bitplanes.   By changing  active bitplanes the color
     of the text will be changed.  It is set to all one's
     (1111 for  four plane mode) whenever the screen mode
     is changed.


EXAMPLE:

     \TEXT PLANE=1011   ;This will set planes zero, two, and
     three active and plane one will be off.



                       **** WAIT ****


FORMAT: \WAIT LIMIT # or NOW # or RETURN # {"NNNNNN"}


     Sets how  long the program will wait for the user to
     respond (LIMIT),  how long  to wait for a return key
     to be  pressed (RETURN),  or how  long to  just WAIT
     (NOW).   The larger the number specified, the longer
     the wait.

     For LIMIT and RETURN, the time units are in seconds.
     For NOW,  it is  the same as for the SPEED option of
     \ROUNDS--about 1/584th  of a  second if you have not
     reset the  clock speed  with \CLOCK.   A value of -1
     will wait forever (until a keypress.)

     \WAIT LIMIT  # is  the amount  of time in seconds to
     wait for  the user  to press  the return  key during
     user input  with \QUESTION.   Unless reassigned to a
     different key  any mouse button is equivalent to the
     RETURN key.

     For the  \WAIT RETURN  # option the value (#) can be
     followed by a comma and an alphanumeric "literal" in
     single or  double quote marks (both quote marks must
     be the same).  This literal will replace the message
     normally displayed  (maximum 78 characters).  If two
     quote marks are coded next to each other, no message
     will appear  (a cursor  will still appear, however.)
     The location  of the  message cannot  be changed (it
     starts at  the left edge of the second line from the
     bottom.)

     If \WAIT  RETURN exceeds the time specified, -1 will
     be placed in variable "B", otherwise 7181, the value
     of the  return key,  will be  there.   Pressing  any
     mouse button  will also end \WAIT RETURN and in that
     case  variable   "F"  will  hold  the  mouse  button
     pressed.   (Unless reassigned  with \BUTTONS,  mouse
     buttons are equivalent to the RETURN key.)

     WAIT NOW  simply suspends  all  processing  for  the
     specified time  or until a key is pressed.  Use this
     option to  give the  user a  fixed amount of time to
     read the screen.


EXAMPLE:
     \WAIT RETURN 20  "SHOW BEGINS WHEN YOU PRESS RETURN"
     \WAIT NOW 584   ;waits about one second.



                       **** WIDTH ****


FORMAT: \WIDTH # {DOTS} {LEFT, RIGHT, BOTH, or CENTERED}
          {PROPORTIONAL}


     Sets the  width in  either characters  or dots  that
     will be displayed on the screen when text statements
     are encountered.  Words are wrapped to the next line
     for  \OVERLAY   and  \SCROLL.     If   specified  in
     characters the  actual  width  of  the  text  as  it
     appears on  the screen  will be  the product of this
     value and the width of the current font.

     You  can   specify  justification  other  than  left
     justified  (the   default).    When  not  specified,
     justification will be LEFT after this command.

     You can  specify  the  width  in  dots  rather  than
     characters.   Proportional font widths should always
     be specified  this way.    The  number  of  dots  is
     rounded down  to a  2-byte (word)  boundary (in  CGA
     mode there are 8 dots per word.)

     You can  use the proportional option even when using
     a non-proportional  font.   For example  when  using
     BOTH  text   justification  you   need  to   specify
     proportional so  that it  will  adjust  the  spacing
     between  words  correctly.    (BOTH  option  is  not
     available for non-proportional fonts.)

     Proportional text  processing can  be  significantly
     slower than  non-proportional, but  usually looks  a
     lot better.

     As of version 7, justified BOTH will justify LEFT if
     it is the last line (or only line.)  Thus, just BOTH
     only works for lines >1 line.



                       **** WRITE ****


FORMAT: \WRITE {drive:}{/path/}NNNNNNNN.EXT


     The only  valid file  that can  be written with this
     command is  an auxiliary file so the EXT must always
     be AUX.   All  other files  will be ignored.  (Print
     files are  automatically written  out 512 bytes at a
     time with \PRINT.)

     Text, hue,  picture and  font files  that you create
     cannot be  written to  disk this  way.  They must be
     written out manually with function key 6.

     As with  \READ, \OPEN and \CLOSE you may specify the
     filename, path,  etc. symbolically.  See  \READ  for
     examples and explanations.



                         **** X ****


FORMAT: \X NNNNNN


     NNNNNN is  a one  (1) to  30 byte  name.   This is a
     place that  \CALL, \CALLM and \JUMP go to.  The name
     must be exactly the same everywhere it is used.  \ON
     KEY and  \ON ERROR  also jump  or call these places.
     This  command  cannot  appear  in  an  \IF  sequence
     (between the \IF and the \ENDIF).



                       **** ZING ****


FORMAT: \ZING AXIS={X,Y or B} CORNERS=#,#,#,# FRAME=#
          LOCATION=#,# MODE={B, F or X, A, O}


     Displays all  or a  portion of a raster frame to the
     active screen.  ZING lets you display a single image
     with more  features  than  \SHOW  or  \RUN,  but  is
     slower.

AXIS={X,Y or B}
     The area  to be  shown can  be flipped  on either or
     both (B)  axis.  This can be combined with all other
     ZING options.

CORNERS=#,#,#,#
     Specifies the  upper left  and lower  right  corners
     within the frame to be displayed. The values are the
     X-low, Y-low, X-high and Y-high dots.

FRAME=#
     The frame to be \ZINGed onto the screen.  Frame must
     be a  raster image.  (Before release 7 the parameter
     LOCATION was  ignored if FRAME followed the LOCATION
     parameter.)

LOCATION=#,#
     Location is  the upper  left corner of the screen to
     start placing  the image.   The  base X- and Y- axis
     values for  the frame  are  added  to  the  location
     specified to determine the actual location.

MODE={X,A, O, B or F}
     Mode puts  this command  in XOR  mode (X),  AND mode
     (A),  OR   mode  (O),   "background"  mode  (B),  or
     "foreground" mode (F). The X, A, O, B, and F options
     are exclusive:  you may  only use  one of  them at a
     time (or  none).  Background means only the non-zero
     dots will  be moved,  and only to pixels which are 0
     on the screen.  Foreground means again only the non-
     zero dots  will be  moved, but  they will  be  moved
     regardless of what is on the screen.

     In XOR  mode the image to be placed on the screen is
     XOR'ed with whatever is currently on the screen.  In
     both "foreground"  and "background"  modes only dots
     in the foreground colors (color numbers greater than
     color number  0) are  transferred to the screen.  In
     background mode  these dots  are only transferred if
     the current  screen dot is the background color (0).
     This allows  objects to  be placed in the foreground
     or background of a current image.



                   **** * (asterisk) ****


FORMAT: \*


     Any command  that starts  with \*  is a  comment and
     does not  affect processing.   This  command must be
     the last  or only  command on  the line.    Anything
     after it (until the CR/LF) will be ignored, even a \
     (backslash).


EXAMPLES:

     \* this paragraph shows horse gaits.
     \READ TROT.PIC
     \APPEND CANTER.PIC 1,9
     \APPEND GALLOP.PIC 1,13
     \APPEND PACE.PIC 1,12
     \X NEXT_HORSE
     \LOCATE 20,20
     \DISPLAY "WHAT GAIT DO YOU WANT TO SEE?"
     \CURSOR 10,5
     \QUESTION #4,0
     \IF #4 = 99
     \END
     \ENDIF
     \IF #4 = 1
     \* TROT
     \SHOW 80,80,1,12
     \ELSE
     \IF #4 = 2
     \* CANTER
     \SHOW 80,80,13,21
     \ELSE
     \IF #4 = 3
     \* GALLOP
     \SHOW 80,80,22,34
     \ELSE
     \* PACE IF NOT 1-3 OR 99
     \SHOW 80,80,35,46
     \ENDIF
     \JUMP NEXT_HORSE



                 **** " (double quote) ****


FORMAT: \"


     The double  quote mark allows you to display a blank
     line on  the screen  in \CRAWL,  \OVERLAY or \SCROLL
     mode.   It is preferable to creating a blank line in
     the text file, which cannot be done anyway using the
     built-in editor.   The  program  will  handle  blank
     lines if it encounters them (presumably created with
     another text editor).

     Any text  appearing after  the  quote  (")  WILL  BE
     DISPLAYED.   You can use this command to display any
     text with  a backslash (\) in the first column.  For
     this reason  this command CANNOT have other commands
     following it  on the  same  line.    They  would  be
     treated as  text.  \ON KEY checking for this command
     is the  same as  for text  lines.  The number of \ON
     KEY checks  that will occur during execution of this
     command will  depend on  the height  in dots  of the
     current font.

     Just blank  lines (13,  10) can  be used  after text
     lines or  after a  \" command,  but not  after other
     command lines.  Therefore, use this command.



                  **** + ((plus sign) ****


FORMAT: \+


     Indicates that no keyboard check is to occur between
     command lines.   This  command is  only valid as the
     last command  on a multiple-command line.  Therefore
     it is  not compatible with \" and \* commands on the
     same line.   This  command causes  multiple  command
     lines to  "behave" as  though they  were all  on the
     same line.   No  \ON KEY  jumps will  occur  between
     lines connected  with \+  so you  can guarantee that
     several processes  (commands) will  all occur if the
     first one  occurs.  If the line after the \+ command
     is a  text line  (or a  \" command  line) \ON KEY or
     keyboard checking  will only  be inhibited  for  the
     first row or column (one dot high or wide).

     This command  is useful  when setting  up or turning
     off multiple \ON KEY specifications.  Also it can be
     significantly faster,  particularly if  a  mouse  is
     active, since  calls  to  the  mouse  manufacturer's
     software often take a noticeable amount of time.






                 \RUN Information Displays

     This program  can do  very complex  animation.  You can
use  combinations   of  windows,  paths,  masks,  controlled
motion, xor  and animation  sequences to  display raster  or
vector pictures, or strings within vector pictures.
     \SPRITE  information   remains  set  until  either  you
restart your  text file  (in the editor, from line 1) or use
\CLEAR SPRITES.  For example if you enter a path for sprites
to follow  all \SPRINT  commands that  are executed  will be
assigned that  path until  you either  reset to  a new or no
path or  execute \CLEAR SPRITES, which sets PATH equal to NO
(none).
     The program  uses over  140  bytes  of  data  for  each
\SPRINT'ed character.  The program uses a "work area" to set
up the  data.   This area,  called the  sprite table, can be
viewed when  running the editor when \RUN FACTS {#} is used.
Some data  changes with  each cycle.   Viewing  the data can
help you  verify that what you want to occur in an animation
sequence is actually occurring--at least mathematically.
     FACTS displays  values including  the current status of
all the  parameters  you  set  with  \SPRITE.    Also,  such
information as the address of the sprite in RAM, the current
location, etc..
     Most sprite  values, including  current  location,  are
"word" (2-byte)  values.  In the case of location this means
that the "virtual" location can be any value from 0 to 32767
and additionally from -32768 to -1 on each axis.  The screen
only occupies a small portion of this range: for CGA 4-color
mode, positive  numbers 0-319 on the X-axis and 0-199 on the
Y-axis with  0,0 being the upper left corner.  If you scroll
a sprite  far enough off the screen in any direction it will
reappear on  the opposite  edge.   You can use the offscreen
area to  "store" sprites  that are active but not located on
the screen  or to  scroll sprites  off the  screen.  If  the
WINDOW= parameter  has been  entered for  a sprite  then the
"active" area  is defined  by the  window  rather  than  the
screen dimensions.
     On the following pages is a listing of where the values
for each  sprite are kept in the data area.  The data can be
shown with the FACTS option of \RUN, when running the editor
version.   First the  program displays  the image  (if it is
supposed to)  and then it displays the first screen of data,
which may overlay the sprite.  Press any key except the HOME
key, the  PG DN  key, the arrow on the four (left arrow) and
the arrow  on the  six (right  arrow) to advance to the next
sprite (NOT  one cycle--unless  you only  have one sprite in
your table).
     Information  is   displayed  for  each  sprite  whether
"active" or  not.  Press Pg Dn (the three key on the numeric
pad) to  see beyond  the first  screen of data.  Pressing it
repeatedly will put you past the current frame and on to the
next one,  but it  will NOT  "wrap around"  after  the  last
sprite-it will  just show  unrelated areas  of  memory  that
follow the  "sprite table".   Byte values are displayed both
numerically and  as a  character if  possible.   If an ASCII
character cannot  be displayed,  a period (.) will appear in
the third  column.  If a word value is at the location to be
displayed only the first two columns are used.
     Press the  HOME key  (the seven key on the numeric pad)
to return to the information at the beginning of the current
sprite.   Press the  left and  right arrow keys (on the four
and the  six)  to  see,  respectively,  the  last  and  next
sprite's information.




              Values at Sprite Table Addresses

Offset Type Meaning

  0  Word Offset from RAM base address for this frame.
  2  Word X-location of first dot.
  4  Word Y-location of first dot.
  6  Word X-location of last dot.
  8  Word Y-location of last dot.
 10  Word X-starting location.
 12  Word Y-starting location.
 14  Word X-current location.
 16  Word Y-current location.
 18  Word X-increment amount.
 20  Word Y-increment amount.
 22  Word picture size.
 24  Word X-low ending position (adjusted by first dot
          value).
 26  Word Y-low ending position (adjusted by first dot
          value).
 28  Word Starting cycle.
 30  Byte Type.  R or anything else.
 31  Byte Frame type byte.
 32  Word Animation cycles limit plus three (3).
 34  Word Animation current cycle (>1 is currently  active).
 36  Word Scroll horizontal recycle amount.
 38  Word Scroll vertical recycle amount.
 40  Byte Was this frame onscreen last cycle (n, y)?
 41  Byte Is this an animation frame (A or not A)?
 42  Word Ending Cycle.
 44  Byte Does this frame follow a path (P)?
 45  Byte Xor? (not capitalized--is a, o, x, or R for AUTO
          REMOVE, or n or y).
 46  Word Path offset of first dot.
 48  Word Path offset of last dot.
 50  Word Path offset of current dot.
 52  Word Screen address of first byte for Auto-xor (X16).
 54  Word Offset of first byte from 52 (Auto-xor).
 56  Word RAM base address of frame (X16).
 58  Word Frame number for this sprite.
 60  Word Window lower-right X-value.
 62  Word Window upper-left Y-value.
 64  Word Window lower-right Y-value.
 66  Word Starting vector string dot number position.
 68  Word Ending vector string dot number position.
 70  Word Address of path frame (X16).
 72  Word Path frame number.
 74  Word Window upper-left X-value.
 76  Word Previous cycle X-location.
 78  Word Previous cycle Y-location.
 80  Word Add-amount for vector string starting dot.
 82  Word Previous cycle starting position for string
          display.
 84  Word Add-amount for vector string ending dot.
 86  Word Previous cycle ending position for string display.
 88  Word Height of image to be Auto-XOR'ed off.
 90  Word If raster, Auto-XOR bytes to skip (not shown).
          If vector starting string dot address.
 92  Word If raster, Auto-XOR source address of first byte.
          If vector, ending address for string repeat.
 94  Byte Auto-XOR bit mask for the left edge. (Raster.)
 95  Byte Auto-XOR bit mask for the right edge (Raster.)
 96  Byte Auto-XOR number of bits to shift image.(Raster.)
 97  Byte Unused.
 98  Word Address of last "active" dot (next-to-last dot).
100  Word X-high end window value (adjusted if vector).
102  Word Y-high end window value (adjusted if vector).
104  Byte Keep? (Y).
105  Byte Connect line segments? (Y) (Vector).
106  Byte Fast display? (Y) (Raster).
107  Byte Zing? (Y).
108  Word Zing offset address.
110  Word Zing base address.
112  Word X-location for Zing.
114  Word Y-location for Zing.
116  Word X-low increment for OPEN or WPATH current dot
          address.
118  Word Y-low increment for OPEN or WPATH first dot
          address.
120  Word X-high increment for OPEN or WPATH last dot
          address.
122  Word Y-high increment for OPEN or WPATH base address.
124  Word WPATH path frame number.
126  Word WPATH X-width of window.
128  Word WPATH Y-width of window.
130  Word WPATH X base window location.
132  Word WPATH Y base window location.
134  Word ZING word width of image.
136  Word ZING dot width of image.
138  Word ZING dot height of image.
140  Word Auto-XOR bytes to show (raster).
142  Word Sprite ZING frame.
144  Byte Pattern-foreground mode (F) or not F.
145  Byte Not used.  Reserved.
146  Word Sprite ZING bitplane size.
148  WORD Bitplane size.






               Picture and Font File Formats


     Picture and  font files  are designed  with  a  "header
record" of  at least  26 bytes  followed by the data for the
frames themselves.   Each  picture frame  has a sixteen-byte
frame header.   Proportional  fonts have  a ten-byte header.
Standard fonts have no frame header at all.



     The font  file header  is 26  bytes.   The picture file
header is 26 bytes plus 2 bytes per frame.  These additional
bytes hold  the size  of each frame:  \APPEND reads this and
then calculates  the locations in the file of the frames you
ask for.  If the file is compressed, whether font or picture
format, the header will have an additional 2 bytes per frame
containing the  frame's compressed  size.   A value  greater
than or  equal to the non-compressed size means the frame is
not compressed.  Vector frames are not compressed.

     The format  of the  26-byte file  header is as follows.
Bytes not used are reserved for future use.


Offset Type Meaning

 0   Word Unsigned low-order word for the total size of this
          file.  If non-proportional font this is the frame
          X width.
 2   Word Unsigned high-order word for the total size of
          this file.  Always zero prior to release 6.00.  If
          non-proportional font this is the Y height.
 4   Word Width in words of the last frame used.
 6   Word Picture size of the last frame used.
 8   Word Total frames in the file.
10   Byte Total number of "sectors" in the file. (This value
          is not used after release 3.46).
11   Word Size of this header record.
13   Word Size of each frame header record.
15   Byte Bytes per dot for vector frames.
16-19     Bytes     Release number of program that wrote the
          file.
20   Byte Graphics mode the picture file is for.  CGA is
          represented by a 4 and is the only valid mode
          before release 6.00.
21   Byte Compressed? ("h" before release 4.80, 0 (no) or 1
          (yes) after.)
22   Byte Palette for this picture file.
23   Byte Background for this picture file.
24   Byte Dots per byte for raster images.
25   Byte Picture bitplanes.



The format of the frame header is as follows:

Offset Type Meaning

 0   Word Width in dots (0=1 so one less than actual).
 2   Word Height in dots (0=1 so one less than actual).
 4   Word Width in words (dots per word depends on frame
          resolution).
 6   Word Picture size in bytes (less than approximately
          64016).
 8   Byte This is a bit-mapped field.  The lowest (0th or
          rightmost) bit is the image type, Vector (1) or
          Raster (0).  The next bit to the left is the mask
          bit if raster.  Next, a bit indicating whether the
          mask was manually edited.  (1 if it was, 0 if it
          wasn't.)  Next is a bit indicating whether the
          frame is an onion skin frame (1) or not (0).  Then
          a bit
          which is currently unused but reserved--set to 0.
          Then, two
          bits which are also currently not used except by
          SCRNSAVE--
          They indicate that the frame should be a
          continuation frame
          or a base frame.  The low order bit is set to 1 if
          a base frame and the high order of these two is
          set to 0, then the
          continuation frames are both 1's, then the LAST
          continuation
          frame is a 1 in the high order and a 0 in the low
          order bit.
          Lastly is a bit used in RAM, indicating that the
          frame has
          been changed in the editor.  Normally this bit is
          set to 0.
 9   Byte Header size for the individual frames.  (16 for
          pictures, 10 for proportional fonts.)
10   Word Base X-location coordinate.  (If picture file.)
12   Word Base Y-location coordinate.  (If picture file.)
14   Word Base timing value.  (If picture file.)

     For a vector frame the total size is the number of dots
times the  bytes per  dot, plus  the header.   For  a raster
frames with  a mask  the mask immediately follows the actual
frame data.   Thus  the frame  size is  the header, plus the
picture data size (calculated from the horizontal word value
and the  vertical height),  plus the  mask if  a mask exists
(same size as the picture data).

     Raster images  are normally  compressed when written to
disk. The program calculates the bytes that can be saved (if
any)  and   if  the   value  is  significant  it  recommends
compression.  You need not compress but the disk savings can
be substantial.   Decompression usually takes less time than
reading the  larger file  so it  is seldom  desirable not to
compress if the program recommends it.

     The compression format is a standard algorithm:  If the
top two bits (high-order or left-most) of the first byte are
both ON  (11xxxxxx) then  the other  six bits  indicate  the
number of bytes that the next byte is repeated.  In CGA mode
each byte represents four dots.

     The six bits that indicate the number of times that the
next byte  is repeated  is one  less than  the actual count.
The binary  value 11000000  would indicate  one byte of data
(use the  following data byte one time) while 11000001 would
indicate two bytes that are the same.

     If the top two bits are not both on then the byte is an
actual data  byte.   In this  case the  following byte would
then be checked to see if its top two bits are both on.

     The header  portion of each frame and the header for
the entire file are never compressed.






               Format for the Auxiliary File

     The auxiliary  file has  a 9  byte header  and then the
individual  auxboxes.     Each  auxbox  also  has  a  header
containing the  number of  the auxbox, it's type and length.
The last  auxbox is  always #32767 and contains the time and
date that  the auxfile was written out to disk.  This auxbox
must be included in the auxfile.
     The format of the header record is as follows:


Offset Type Meaning:

  0  Word Size in bytes of the auxfile.
  2  Word Size of this header record (always 9).
  4  Byte Not used in release 6.00.  Set to 0.
  5  Byte Major release number of program that wrote file.
  6  Byte A period (.).
  7  Byte Tenth's digit of minor release number.
  8  Byte Hundredth's digit of minor release number.

     The individual  auxboxes are  stored in  the  following
format:
Offset Type Meaning:

  0  Word Number of this auxbox (auxboxes are always stored
          in numerical order).
  2  Byte Type of this auxbox.  Either # or L in release
          6.00.
  3  Byte Size of this auxbox.  For numeric auxboxes (type
          #) this is always 2.  For alphanumeric auxboxes,
          it is the length of the data within the auxbox.
  4  .... The data follows the 4-byte header info for each
          auxbox.  For numeric auxboxes (type #), this is a
          signed binary word value.  For alphanumeric
          auxboxes it is the ASCII characters that are
          stored.







                  Format for the Hue File

     The hue  file (extension  .HUE) contains  a sequence of
hue color  definitions.  It is specifically for a particular
screen mode,  and it's  maximum size  is  dependent  on  the
number of  colors in  that screen mode.  The header contains
the "from" and "to" colors that the hue file contains.
     The format of the header record is as follows:


Offset Type Meaning:

  0  Word Size in bytes of the hue file.
  2  Word Size of this header record (always 16).
  4  Byte Not used (reserved).  Set to 0.
  5  Byte Major release number of program that wrote file.
  6  Byte A period (.).
  7  Byte Tenth's digit of minor release number.
  8  Byte Hundredth's digit of minor release number.
  9  Byte Screen mode this hue file is for.
 10  Byte Dot mask for above screen mode (maximum color
          number).
 11  Byte Palette.
 12  Byte Background color.
 13  Byte Hue low-color.
 14  Byte Hue high-color.
 15  Byte Reserved.  Set to 0.

     The individual hues are stored in the following format:

Offset Type Meaning:

  0  Byte Red component of color.
  1  Byte Green component.
  2  Byte Blue component.

     Each component  should be  between 0  and 63.   If  any
value is  greater than  63  that  component  value  will  be
ignored.






                    Space Considerations

     When using  RAM for  pictures, this  program uses space
for pictures  "as needed."   When a picture file is read all
previously  allocated   RAM  memory   is  returned  to  DOS.
Whatever amount of memory is needed for the new file is then
requested  from  DOS.    Whenever  space  is  requested  DOS
allocates an  additional 16 bytes for it's own use.  Also it
rounds the  request for  space up  to the  nearest  16  byte
boundary in  RAM.   The effect  is  simply  that  allocating
memory for  a lot  of frames  at once is more efficient than
allocating one  chunk at a time.  When you \APPEND frames to
a picture  file the  frames that  are to be appended will be
put in  as few requests to DOS for space as possible, so you
may save  a few  bytes by  appending all the frames you will
want at  once.  You also reduce disk access by not having to
access      the      file      as      frequently.      When
creating/inserting/deleting frames in the picture editor the
program will  return memory  to DOS  if possible, but if the
frame was  part of  a group  of frames  the memory  will  be
"lost" until  a new picture file is read in, or until all of
the frames in that allocation block are deleted.
     Since the  program can  use as  much memory  as DOS can
give it  (up to  640K), it  can take  a long  time to use up
memory in  a "loaded"  machine.   If you  start running into
errors whose explanation is that you have run out of memory,
try writing  out your  picture file  and reading  it back in
because any  changes to  the frame  count  may  have  wasted
space.
     If EMM  memory is available and it's use by the program
has not  been inhibited though the use of startup variables,
the memory  is always used in 16K (16384 byte) chunks called
pages.   Again it  is worthwhile to read as many frames at a
time as possible to conserve space.
     Disk-based animation  uses two  64K-byte areas  to read
and decompress the frames.
     You can  use the  startup variables  to set the maximum
font size  to the  minimum,3K bytes, but then you may not be
able to  read larger fonts into RAM.  (For many screen modes
3K is not enough to read even a very small font.)
     When the  program initially  loads the  total amount of
RAM available  for pictures  is in  variable "A" (in K), and
the amount  of EMM  (if any)  is in  variable "O" (in 16,384
byte "pages").   You can get some information about how much
is still available at any time using \MEMORY.
     If you still can't get enough memory for the program to
run  properly,   there  are   several  third-party  software
packages such as QEMM from QUARTERDECK OFFICE SYSTEMS, Santa
Monica, CA, which will maximize RAM usage.






             Tips On Making Your Program Faster

     Text file  design can  have a significant effect on how
fast a  program runs--or  appears to  run.   There are  many
things to  consider.   In order to make the program run fast
at the  right times  you might  try reading disk files while
the user  is looking  at text  or non-moving  images on  the
screen.  If you set the text pause length to something other
than zero that pause occurs between each line (one dot high)
during display of text.
     \ON KEY  commands store  the actual address in the text
or macro  area that  the keypress  should bring  you to  and
therefore  execute   very  rapidly--except  for  the  "human
element" of course!
     Variables  can   be  evaluated  a  little  faster  than
auxboxes.   Single-digit auxbox  numbers (#1, #2, etc.) will
evaluate faster than named or high-number auxboxes.
     Use \+  commands often.   The keyboard and input device
check can  take a noticeable amount of time, especially if a
mouse, joystick,  or digitizer is active.  Turning the input
device  off   when  not   in  use   can  speed  you  program
significantly.   Some mouse  software (usually supplied with
the mouse) is notoriously slow.
     \SHOW is generally faster than \RUN.
     If raster  frame widths  are evenly divisible into word
boundaries they  can be  displayed especially  fast.   \SHOW
automatically places  such frames  on the  screen at maximum
speed.   Use \SPRITE  FAST=YES to speed \RUN.  Masked frames
are substantially slower than non-masked images.
     The speed of animation is largely dependent on the size
of the  pictures being shown.  To increase the speed be sure
to use  as small  an image as possible for the portion being
animated.
     For maximum  speed set  \CLOCK SPEED=  to 1,  which  is
about 18.2  times per  second.   This will  give very coarse
speed control but if that's okay, it will use less processor
time for the asynchronous clock interrupts because they will
occur less  often than at the default (584 times per second)
or some other speed.  The minimum is 18.2.






                  Uses of the "escape" key

     The escape key performs many related functions.  When a
text file is running in the editor version or at any time in
the runtime  version ESCAPE  allows you to end the execution
of the  text file.   In the runtime version this will return
you to  DOS.  In the editor version you are given the option
of single-stepping  the file  or you  can return to the text
editor.   The messages  displayed are non-destructive of the
screen.
     If  you  choose  to  restart  the  program  nothing  is
changed.  Variable "B", which holds the last keystroke, will
NOT be  changed and  no \ON  KEY jumps  or calls  will  have
occurred.   If you  choose "single-step"  in the  editor the
program will  pause for  input before each line is executed.
Whatever key  you press  is treated  as a regular keystroke.
To stop  "single-step" mode  press ESCAPE  and do not select
single-step as the option.
     In the  editor ESCAPE  lets you  get out  of text lines
unchanged or resets picture frames.
     Functions that require answering additional prompts let
you  use   ESCAPE  to   leave  the  option  unused.    While
transferring between  text and  draw mode ESCAPE substitutes
the default answer (usually "Y").
     In the  editor version  ESCAPE is  for stopping, giving
up, changing your mind, backing out, etc.






           F10-"Instant" commands & DOS functions

     In the  editor version function key 10 gives you access
to "instant"  commands.   Most commands such as \DRAW, \LINE
and so  on are  allowed.   Since only  one command  will  be
executed, commands  that send  you to different areas of the
program  are  not  valid  (\CALL,  \JUMP,  etc.).    Invalid
commands will  produce an error message.  Certain "powerful"
commands such as \DELETE are also inhibited.
     If you  press F10  twice in a row you will get a choice
of DOS  options including Rename a file, Copy a file, change
the current  drive or path (P), Erase a file, check Space on
disk drives,  take a  directory of  a drive,  or  execute  a
second copy  of COMMAND.COM.   Copy,  Directory,  Erase  and
Rename can  all be  stopped  before  execution  by  pressing
ESCAPE.  Directory can also be stopped during execution with
ESCAPE.
     When a  directory is  being displayed  pressing any key
will  freeze   the  display.    Pressing  another  key  will
continue. ?  and *  ("global" characters)  are valid in file
names here.  When all entries for the current directory have
been displayed the total number of files and the total bytes
used by those files are displayed.
     The Copy  function copies only one file at a time.  The
name  must   be  completely   specified   without   "global"
characters (* and ?).  (Asterisks (*) and question marks (?)
may be  used in  the  output  file  name.)  Drive  and  path
specifications may be included.
     You can  change both  the current  path and  drive with
'P'.
     For the  COPY, DIRECTORY,  and RENAME  commands you can
specify ,H  (Hidden) ,R (Read Only) and ,S (System) options.
This will  set or  search for  these attributes.  To include
these options  separate them  from the  filename by  a comma
with no  intervening spaces.   ,H  ,R ,HRS  and ,RH  are all
valid.  For input files and directory searches the ,H option
will allow  the handling  of "hidden"  files, which normally
are not  displayable or  copyable.   If these attributes are
not specified  for output  files they  will not  be  applied
regardless of the input file's attributes.






                    Future Enhancements


     This product continues to evolve.  Your suggestions are
the most  important input  for future  enhancements.    Some
expected, or possible, future enhancements include:

     Decimal  numbers  are  certainly  an  important  future
enhancement.   The variables  and default  types of  numeric
auxboxes will  undoubtedly remain whole numbers between -32K
and +32K to maintain speed of operation.

     Greater  than   64K  pictures.     This   is  partially
implemented in the SCRNSAVE utility but then not used in the
main program in release 7.

     Three-dimensional vector  images,  and  object-oriented
images.

     Better mouse  cursors.   (Mask capabilities  for cursor
crosshairs.)

     What would  YOU like  to see in future versions of this
program?  Send a letter to the author! (S.A.S.E. preferred.)
All requests  will be  considered plus  you'll  get  on  the
company mailing  list, useful  for learning about additional
products that may be of interest to our users.






            Of Mice and Joysticks and Digitizers


     This program  will use  any of  these devices for input
while drawing  or for  \MOUSE.   Even if  an input device is
active the  eight cursor  direction keys around the 5 key on
the numeric  keypad can  be used (on PC and XT type machines
the 5  key can  also be  used.)   The numeric keys above the
QWERTY portion  of the  keyboard can also be used for faster
travel around  the screen.   If you have installed the mouse
software prior  to loading  this program it will utilize the
mouse automatically.

     Only one input device can be "active" at a time, except
that the  MOUSE and  JOYSTICK can  both  be  used  together,
although  this  can  require  significant  amounts  of  time
(overhead.)

     The mouse  uses Microsoft  compatible software calls to
accomplish it's  job.  This software should be loaded before
loading this  program.    It  can be loaded after processing
starts with  \EXECUTE but  shouldn't be.    See  your  mouse
documentation for  how to load your mouse "driver" software.
In the editor, you cannot initialize the mouse for the first
time if  changes exist  to any  files in RAM.  The following
example would  load the  mouse software named mouse.com from
drive "A":

\EXECUTE >A:MOUSE.COM

     The entire  name including  the  extension  has  to  be
specified.  Again, mouse software should be loaded first!

     The reason it is not a good idea to load mouse software
from within  this  program  is  because  mouse  software  is
usually "TSR"  (Terminate, Stay  Resident) software.    Such
software will (probably) load in the first available spot in
memory and  stay there.   Thus  it will probably divide your
computer memory  into two  chunks if loaded from within this
program (until you reboot).






                   Timing Considerations


     This program  utilizes the  system clock at an enhanced
rate for  most timed  activities.   This way the timings you
set will  be approximately  the same  on any  machine of any
speed.  Not all functions are timed.  Timing values of 0 and
-1 have  special meaning.    0  (zero)  means  "as  fast  as
possible" and  will run at different speeds on machines with
different speeds.   -1  generally means  "run  forever"  (or
until ESCAPE or "any key" is pressed).

     The values  you code for timing have different meanings
for different  commands.   Specifically those  that  are  in
effect during  user input are in seconds, and those that are
for animation and other graphics are in small fractions of a
second (approximately 584 "beats" per second).  In the SPEED
parameter of \ROUNDS, and in \OVERLAY, \SCROLL and \WAIT NOW
a value  of 584 would be about one second.  For \WAIT RETURN
# and  \WAIT LIMIT  # the  value coded  refers to seconds to
wait.  -1 is forever.


     Remember two things about creating animation for a wide
range of  machine speeds:  First, when setting up artwork on
a fast  machine remember  to consider  how it will look on a
slower machine.  Second, if creating on a slow machine don't
forget that  some things  will go TOO FAST on a fast machine
unless  you  limit  their  speed  with  the  various  timing
controls.   For example  if a \ROUNDS # SPEED 10 value looks
good on  a plain  PC find  out if  \ROUNDS #  SPEED 20 looks
exactly the  same.   If it  does then  on a fast machine the
action might  be twice  as fast!   This  is because  you are
displaying something  that can't be done (on a slow machine)
in  less   than  20   ticks  of  the  timer  (each  tick  is
approximately 1/584th of a second.)
     The speed control values you choose should be the one's
you actually  want.   0, which  is "as fast as possible" may
look fine on a PC, but on an AT or 80386 type machine it may
be too fast.






           Converting Images Between Screen Modes

     Conversion is  done by  reading a  picture of  one mode
into the program while in another mode.  You can specify the
mode to  become in  the P11FLAGS= SCREEN:#,#,# environmental
variable or  on the  command line  as [SCREEN:#,#,#].   When
moving "down"  in  number  of  colors,  you  can  chose  the
"clipped" or  "modulo" method.   Clipped  makes  all  colors
higher than  the maximum  color equal  to the maximum color,
while modulo  makes the highest+1=0, highest+2=1, and so on.
When converting, the new picture will, as the old one was in
it's screen  mode, be  on a  byte boundary on the left edge.
Therefore, when  going to  a higher  X-axis resolution, some
frames may not match up correctly with other frames and will
need to be manually adjusted afterwards.
     Only  frames  up  to  screen  size  will  be  converted
completely. Vector  frames will  not be converted, so colors
may be  unusual when  moving "down" from more colors to less
colors.






           Executing DOS from within the program


     This feature gives you a lot of power, but can cost you
dearly if misused.  It is best NEVER to use it when you have
changes in  RAM, especially  with earlier  (2.X) versions of
DOS.   You  can  do  anything  you  have  the  memory  (RAM)
available for.   You  can run  any program,  execute any DOS
command, format  disks, etc. etc. etc..  There is NO limit--
you can  even run a second copy of this program. (If it will
fit.)

     From DOS,  return to this program either by typing EXIT
at the  DOS prompt  or by having that word in a "BATCH" file
that DOS  executes.  You cannot execute a batch file without
loading the  command processor  so you  must  use  the  DOS>
option of  \EXECUTE for batch files.  You can also exit to a
second copy of the command processor by typing F10 (function
key 10) twice from the editor and then pressing "X" (EXIT).

     When processing  returns to  this program it will reset
the screen mode if necessary.  However if some other program
changed the  palette and/or  background, or  the  hues,  the
program will  not be  aware of this change.  If this command
fails variable "A" will normally contain -1 and variable "C"
may contain an error code.

     The clock,  which is  speeded up to about 584 ticks per
second (or  some other value you set with \CLOCK SPEED=), is
temporarily reset to normal for \EXECUTE.

     Any program  you run  that destroys  the current screen
memory  area   would  also   have  destroyed   your  screen.
Therefore you  may want to execute \CLEAR SCREEN immediately
upon return in those instances.

     Although you  can "theoretically"  execute any  program
with this command you should avoid certain types of programs
known as  "TSR" (Terminate,  Stay Resident)  programs.  When
loaded these  programs usually take the next available chunk
of memory  and remain there until you reboot.  The result is
that when you return to this program, and evermore until you
reboot, you  will have  your memory divided into two pieces.
Keyboard enhancement programs are generally TSR programs, as
are most mouse utilities.  They should be loaded BEFORE this
program.
     The DOS command FORMAT may act much like a TSR program,
dividing memory if executed.  FORMAT should not be used from
within this  program unless  you plan  to reboot afterwards.
Of course,  if your  only other  choice is to loose valuable
work, by  all means  format a  disk, save  your  files,  and
reboot!






                      About the Author


     Version 1.0  of Russell  Hoffman was released in August
of 1956.  He has  been involved  with  microcomputers  since
1980.   In 1984  he started  writing P11  in response  to  a
client request  for an  interactive tutorial about the human
heart.

     Prior to  starting P11  he designed randomized computer
art programs  that create two-dimensional artwork on digital
plotters.   Each drawing  is different from every other.  He
claims they  are examples  of "imitation  intelligence."  By
using random  numbers to  vary the  sizes, colors, and other
aspects of  each drawing,  an infinite artistic variation is
possible.     The  software   concept  behind  this  art  is
applicable to engineering, physics, architecture, etc..  For
example, row-style  housing developments need not all be the
same.   Random variation-within-a-range  can  make  it  more
likely that a purchaser will find the exact house they want.

     About 20,000  random art drawings have been created and
given away  at computer trade shows throughout the Northeast
as of  this  writing.    Completing  this  project  required
writing an  interactive drawing  program (thus  it  was  the
precursor to  P11) for  the NEC  8201-A (a  lap-top computer
similar to  the TANDY  100) as well as many display routines
for driving  both the LCD display on the NEC and a PANASONIC
VP-6801 P30  six-pen plotter.  This led to other assignments
creating artwork  for various  devices  including  monitors,
printers, plotters,  lasers, oscilloscopes, LED-matrix, etc.
etc.

      In  his spare  time (something  he had  a lot  more of
before starting P11), Russell creates comedy radio routines,
which have been played on the Dr. Demento Show and elsewhere
(1979, 1986).   He  is an avid aviation buff and is learning
to fly  a Cessna  172 Skyhawk,  having soloed  in 1988.   He
likes ocean and lake swimming, reading, photography and loud
music. Also  quiet music,  dancing and  chocolate.  He likes
watching  Jai  Alai,  listening  to  baseball,  and  playing
softball.   It goes  without saying  that he  likes  playing
video games!

     Over 200  of  his  commentaries,  humorous  essays  and
letters have  been published  in and out (mostly out) of the
computer field.   He  lectures to  computer user  groups, as
many as 50 lectures/year.
     He has  several listings in various biographical titles
for his work, and is a member of the Boston Computer Society
and the  Connecticut Computer  Society.  He is also a member
of the  International Platform  Association, WINGS fun club,
Debbie Gibson fan club, and The Demento Society.

     Russ attended  the  Computer  Processing  Institute  in
Bridgeport, CT.  in 1980, Connecticut School Of Broadcasting
in Stratford,  CT in  1979, County School of Tractor Trailer
Driving in  Bridgeport in  1978, and  Penn State University,
State College,  PA in  1974.   (P.S.U. was  the only  one he
didn't graduate  from.) He  attended  (and  graduated  from)
Greens Farms  Academy in  Greens Farms,  CT, where  he first
made contact with a computer via a Teletype machine.

     He has  dabbled extensively  in electronics  but claims
that everything  he builds  either smokes, or shocks him, or
doesn't work.