DISK OR NETWORK FILES

To open a disk or network file the format of the FX: statement is as follows: 

       FX:pathname 

Where the word pathname represents the name of the disk file or network node 
you wish to connect to. The pathname is formed per DOS file name conventions 
for specifying drive, directory, root file name, and file suffix. If the file 
exists, then it is made available for the PILOT program to read from or write 
to. If the named file does not exist, then the FX: statement automatically 
creates a file with that name, containing zero bytes of data. The file is 
made available to read from or write to. The FIZ function may be used to 
determine whether a file exists prior to attempting to open it.  

A disk file can be thought of as a list of bytes numbered from 0, for the 
first byte, up to the size of the file. To read data from the file use the 
FI: statement as shown above. The position-expression is evaluated to a 
number.  The number represents an offset from the beginning of the file where 
reading is to begin. The byte at the specified location in the file is the 
first byte read into the string variable.  The number of bytes copied into 
the string variable is equal to the maximum length established for the string 
variable when it was created. If the FI: statement attempts to read beyond 
the length of the disk file, then the string variable is padded out with 
CHR(255) characters to its maximum length.  

EXAMPLE 1: Open a disk file named DATA, read 20 bytes from the file, starting 
at byte position 15.  

       D: B$(20)
       FX: DATA
       FI:15,B$

The FO:, or FILE OUT statement can be used to write data into a disk file. 
The position-expression determines the byte offset in the file where data is 
first written. The number of bytes written to the file is equal to the length 
of the data expression on the FO: statement.  

In using disk files you can think of the disk file as a long string of bytes. 
Each byte is addressable by its byte offset from the file start. However, it 
is often convenient to think of the file as a series of records, each record 
being a pre-determined number of bytes in length. For example, assume that 
your goal is to keep a file of student names and scores. You may decide that 
the file will consist of a series of 50-byte records. Each one would hold the 
name and score for one student. Also assume that in the first record of the 
file is the number of the next available record in the file.  The following 
program examples show how to set this file up initially and how to write a 
record into the file. This example illustrates the use of the file 
statements.  In practice, you would use KEEP to simplify the task.  

EXAMPLE 2: create file to save student scores

       FX:RECORDS        (create file named RECORDS)
       FO:0,"  1"        (write 1 into the first record)

EXAMPLE 3: save a student name and score in the RECORDS file  

       R: set up strings 
       D:NAME$(30),REC$(50),X$(3)
      . . .  program runs here, assume that student
      . . .  name is stored in NAME$, and score is
      . . .  in the numeric variable SCORE
       R: construct student record with trailing
       R: CR and LF characters 
       C:REC$(49,2) = CHR(13) !! CHR(10)
       C:REC(1,30) = NAME$
       C:REC(31,18) = SCORE
       R:determine next available record
       FX:RECORDS
       FI:0,X$   
       FO:X$,REC$
       R:update record number at the start of file
       C: X$(1,3) = X$ + 1
       FO:0,X$
       FX:

PRINTER OR AUXILIARY PORT FILES 

The system printer device, or the auxiliary RS-232 serial interface can be 
accessed as a PILOT file.  These special files can be used for output only. 
To open the printer as a file use: 

       FX:PRN:

To open the serial interface as a file use: 

       FX:AUX:

The serial interface can be used as a simple control mechanism for video disc 
or other external devices which have an RS-232 interface.  One consideration 
for such devices is that both the computer and the other device must be set 
up to communicate at the same baud rate (speed).  The baud rate on the 
computer end is set up prior to starting your PILOT program by issuing the 
DOS MODE command. This command could be placed in your AUTOEXEC.BAT file so 
that it happens each time the computer is turned on. A sample MODE command to 
set the baud rate to 1200 baud might look like this: 

       MODE COM1:1200,N,8,1

See the DOS manual for further information on the MODE command.  

Once open, the FO: statement may be used to write data to the printer or to 
the device attached to the serial interface. The format of the FO: statement 
is: 

       FO:0,expression

The "0" is ignored for these devices. The string value of the expression is 
written to the device. No extra control characters are automatically written 
after the expression value. If you wish to transmit a RETURN or LINE FEED 
after the data, you must append these characters to the data.  

EXAMPLE 4: Write a line to the printer, then space the printer up one line.  

       FX:PRN:
       FO:0,"Hello world." !! CHR(13) !! CHR(10)


EXAMPLE 5: Control Video Disc Player From PILOT.  This example assumes that a 
Pioneer LDV-700 and Pioneer IU-04 interface is attached to the serial 
interface and that the baud rate has been set via a MODE command prior to 
running the PILOT program.  

       FX:AUX:
       R: next play frame 1000 as still frame
       FO:0,"F1000SI" !! CHR(13)
       R: next line plays 5 sec from frame 2345
       FO:0,"F2345SP@5" !! CHR(13)
       R: next line turns off video disc
       FO:0,"Q" !! CHR(13)

The actual command strings written to the video disc player by the above FO: 
statements may change for another brand or model of disc player. But the 
method used in PILOT to control the device is the same for any device which 
has a serial, RS-232 interface.     

HEAP FILE

The heap facility permits the PILOT program to make use of very large 
computer memory as a temporary, very fast file. The program creates a heap 
out of otherwise unused RAM. Once the heap is created the program can write 
string data to the heap, and read it back later in the program.  In effect 
the heap becomes an unlimited extension to the program string space.  When 
the program ends and returns to DOS the contents of the heap are discarded.  

To establish the heap execute the following statement once at the beginning 
of the program use:  

       FXH: n

where n is a number indicating the size, in bytes, to be set aside for the 
heap. An XSPACE error occurs if the amount is to great for the system in use.  

To estimate the maximum size of the heap for a particular system proceed as 
follows. From DOS before running PILOT run CHKDSK to get the amount of unused 
memory. From that subtract 182K for PILOT. The remainder is available. If the 
program is to call other programs or languages (via EXEC) you must leave 
sufficient unused space for those programs.  

Only the first successful FXH: statement has an effect. Once the heap is set 
up, other FXH: statements are ignored.  

The heap does not count as the one allowed open file. So even though the heap 
is in use one additional disk file may be open.  

To write data to the heap use the following: 

       FOH: n,string-value

where n is the byte position within the heap at which the string-value is to 
be written. The first byte position in the heap is location 0.  The string 
value may be a string variable name or any string expression.  

To retrieve the data into a string variable again use the statement: 

       FIH: n,V$

where n is the position in the heap from which the data is to be read, and V$ 
is any string variable name.  

The statements FOH: and FIH: work exactly like FO: and FI: for disk files. 
The difference is that writing and reading the heap is very fast, taking no 
more time than a simple assignment statement. The heap can serve as a quick 
access storage bin for sprite tables, graphic images, machine language 
subroutines, etc.  

Items to be loaded from disk files into the heap must be moved there through 
string variables by reading from disk to the string via FI:, then writing to 
the heap from the string via FOH:.  

EXAMPLE 6: Create a heap and move two  graphic images to the heap.  

       FXH: 30000
       DX:P$(10000)
       FX:PIC1.SQZ
       FI:0,P$
       FOH:0,P$
       FX:PIC2.SQZ
       FI:0,P$
       FOH:10000,P$

EXAMPLE 7: display a graphic image from the heap 

       FIH:10000,P$
       V:P$

See also:  AUX(0) function,  FIZ function,  MODE (DOS manual) 

GRAPHICS - display graphic images 

       G: turtle-graphics-command-list
       GX: graphics-image-filename
       GSX: graphics-image-filename

The GRAPHICS statement is used to control the graphics screen display. There 
are several types of graphics which can be used: 

TURTLE GRAPHICS: to draw colored points, lines, and shapes either by absolute 
pixel coordinates or by directing an invisible "turtle" to walk in various 
directions while drawing a line wherever it has gone.  Turtle graphics in 
PILOT is similar to what is found in the LOGO language.  

IMAGE GRAPHICS: a graphics image is a stored picture or full screen graphic 
that has been created outside of the PILOT program and stored in a disk file. 
The GX: statement can display such a picture by painting the entire image on 
the screen in one operation.  

SCREEN SAVE/RESTORE: To facilitate the creation of dialog boxes, pull-down 
menus, and other types of screen overlays, the GSX: and GX: statement provide 
a way to take a snapshot of the screen, save it in internal memory, then 
instantly put the screen back as it was on command.  

SPRITE GRAPHICS: a sprite is a smaller picture which can be placed anywhere 
on the screen or can be moved around (animated) on the screen by attaching it 
to the turtle, and allowing the turtle to "drag" it around on the screen.  

TURTLE GRAPHICS

The turtle graphics commands are valid only for graphic screen modes, namely 
modes 4, 5, 6, 13, 14 and 16.  

The G: statement is used for turtle graphics.  After the colon you can write 
a list of turtle graphics commands. The list can contain one or more of the 
following commands, separated by ";" characters.  To draw lines you tell the 
(invisible) turtle which direction to head and how far to walk.  As the 
turtle walks it can leave a colored line on the screen.  The turtle's heading 
ranges from 0 degrees (straight up) to 359 degrees with the heading angle 
increasing as it rotates to the right.  If the turtle walks off the screen it 
comes back on the opposite edge.  In the command descriptions below n 
represents a numeric variable, an integer constant, or an expression enclosed 
in parentheses.  

Ar,d - arc or circle

Draw an arc with radius of r turtle steps, starting at the angle equal to the 
turtle heading, and sweeping through an angle of d degrees. The turtle 
heading rotates right by d degrees, the turtle location remains unchanged. If 
d=360 a circle is drawn 

Bx,y - solid color bar

Draws a bar, or solid box, with the upper left corner at the turtle location, 
x and y are the number of pixels across and down of the bar.  The turtle is 
moved to one pixel down and to the right of the bar.  

Pn - paint an area

Paints an area to color number n. The painted area starts at the turtle 
location and includes all adjacent pixels with the same color as the starting 
pixel. It is a flood fill which recursively wraps around all corners and 
shapes as necessary.  

Hn - set turtle heading to n degrees 

Rn - rotate turtle heading right n degrees 

Ln - rotate turtle heading left n degrees

Fn - walk forward n steps

Gx,y - set turtle location to pixel x,y

Dx,y - draw a line to pixel location x,y

Cn - set line color for F or D to n (0-3)

Cn,w - set line color and line width  

The width can be set to 0 (no line), 1, 2 or 3.  The default is a 1 pixel  
wide line.  The  line width affects  draw, forward, and arc commands.  

E - erase screen to background color

*n(...) - repeat the enclosed commands n times

Wn - wait, or delay n 60ths of a second

Xn - set horizontal scale factor 

Yn - set vertical scale factor

S var$ - make string variable var$ the current sprite table 

Sn - sprite select

Display, or erase sprite n, and attach sprite n to the turtle. 

S0 - detach sprite from the turtle

Jn - jump back to a previous sprite

Move turtle to location of sprite n and attach sprite n to the turtle. 

MODES AND COLORS

Turtle graphics can be performed in modes 4,5,6,13,14 and 16. In modes 4 and 
5 the screen is 320 pixels  across by 200 down with valid line colors 0-3.  
Color 0 selects the current background color as set by TYPE SCREEN.  Colors 
1, 2 and 3 are determined by the current mode. See the TYPE SCREEN statement 
for more information on modes and colors.  

MODES 4 and 5: 320 x-pixels, 200 y-pixels, colors 0-3
MODE 4 COLORS: 1-green, 2-red, 3-yellow
MODE 5 COLORS: 1-cyan, 2-magenta, 3-white

Background color for modes 4 and 5 is color number 0. It can be selected from 
colors 0-15, with two possible intensities as documented under TYPE SCREEN.  

In mode 6 the screen is 640 pixels across by 200 down with one valid line 
color as set by the TS:Xn command.  

MODE 6: 640 x-pixels, 200 y-pixels, colors 0-1 

With an EGA (Extended Graphics Adapter) the additional graphics modes are: 

MODE 13: 320 x-pixels, 200 y-pixels, colors 0-15

MODE 14: 640 x-pixels, 200 y-pixels, colors 0-15

MODE 16: 640 x-pixels, 350 y-pixels, colors 0-15

SCALE FACTORS

The X and Y scale factors can be adjusted for a particular display to achieve 
uniformity in horizontal and vertical step sizes.  The default value is X1;Y1 
, which makes a turtle step size equal to one quarter of a pixel.  To make a 
step equal to a pixel set the values to X4;Y4.  

Scale factors can also be used to change the aspect ratio between x and y 
directions as shown in the ellipse example below. 

EXAMPLE 1: Turtle graphics examples.

G: *18(F60;R20)        draws a circle

G: *4(F80;L90)         draws a box

G: C2;*5(F160;R144)    draws a red star

G: X6;Y3;*36(F10;R10)  draws an ellipse

G: G10,20;D15,85       line (10,20)-(15,85)

G: G(X+30),40;F(60*D)  expressions as arguments

G: A50,360;P2          a circle, filled in

G: B20,20;B40,40       two bars

G: C1,3;A50,180        a wide-line semi-circle



IMAGE GRAPHICS

A graphics image can be created by the GIE program or by other graphics 
creation products which can produce a 16K bit-mapped screen image, often 
called BSAVE/BLOAD format. Many useful graphics creation products do not use 
the BSAVE/BLOAD format to store pictures on disk.  However, in these cases 
there is often a conversion process that can be used to convert the picture 
files to BSAVE/BLOAD format. The BSAVER utility may be useful doing this type 
of conversion. See also: Appendix C. 

To load a graphics image from a disk file and display it on the screen, first 
insure that the screen is in a graphics mode (4,5 or 6) and set the desired 
background color (if not already set). The following statement shows how to 
do these two things:  

       TS:M4;B2

Then execute the following command:

       GX:filename

PILOT can also save the current screen  display in a disk file by the 
following command:  

       GSX:filename

The GX: and GSX: statements may also be used in text modes (0 though 3). The 
screen image file produced is 2K for 40 column screens or 4K for 80 column 
screens.  Prior to executing a GX: statement to display a text screen, the 
screen mode must be set to the same mode in which the screen image was saved 
via a previous GSX: statement.  

The PIQ utility program may also be of interest when using image graphics. It 
can be used to compress a graphics image from BSAVE/BLOAD format into a 
compact format which takes up less disk space and displays more quickly. PIQ 
also provides for various screen wipes and special effects for partial or 
complete screen images. See also: Appendix C.  

SCREEN SAVE/RESTORE

The GSX: statement can be used to make a copy of the current screen in ram 
memory. The command format is: 

       GSX:           (no arguments follow the colon)   

This command happens instantaneously, so it is useful for saving the screen 
display when the program is to be interrupted for a menu, dialog box, or 
other student-invoked control function.  

Once the screen has been saved, the program can modify the screen as 
necessary to converse with the student. This might involve the display of a 
menu box, help screen, note pad, calculator, or glossary.  When the auxiliary 
function is complete, the screen can be restored to its original state by the 
command: 

       GX:           (no arguments follow the colon)

The screen restore is instantaneous. Not only is the visual data put back as 
it was, but the cursor location, colors, and current and previous viewport 
data is put back as well. It is, however, up to the program to insure that 
prior to execution of the GX: statement, the screen mode is set to the screen 
mode that existed at the time of the GSX: statement. If the mode has not 
changed in the interim, then it need not be changed back again. But if the 
screen mode did change after the GSX: statement, then it must be changed back 
by the TS:Mn command just prior to the GX: statement. The MOD built-in 
function may be useful in determining the screen mode prior to the GSX: 
statement if it is not already known.  

Unlike other uses of the Graphics statement, the uses of GSX: and GX: are 
valid in any screen mode from 0 to 6.  

EXAMPLE 2: SYSX routine using GSX: and GX:

       R: come here when user pushes ESC key
       *SYSX 
       GSX:
       TS:V10,30,5,11
       TX:*******************
         :
         :  M  -  Main menu
         :  C  -  Calc    
         :  G  -  Glossary
         :              
         :*******************
       AS:
       M:M!m
       JY:MENU
       M:C!c
       JY:CALC
       M:G!g
       JY:GLOSS
       *SYSX2
       GX:
       E:
 
       *CALC 
       TX:Input expression
       :such as  123.5 * 7
       :or ENTER to return
       A:
       J(%B=" "):SYSX2
       X:"C:Z=" !! %B
       T:#Z
       W:30
       J:CALC
 
       *GLOSS
       TX:Glossary...
      ...
       W:100   
       J:SYSX2

SPRITE GRAPHICS

A sprite is a picture, similar to a graphics image, except that a sprite is 
smaller. A graphics image is 320 pixels across by 200 pixels up and down (the 
entire screen). A sprite can range from 32 pixels by 32 pixels, to 64 pixels 
by 128 pixels. Sprites can be displayed in graphics modes 4, 5 and 6 only.  

A sprite can be used as a way to draw diagrams or pictures on the screen. One 
of the unique features of a sprite is that it can be animated or moved on the 
screen. This is accomplished by use of the turtle graphics commands of the G: 
statement. To move a sprite you need only "attach" the sprite to the turtle, 
then move the turtle via forward or draw commands. As the turtle moves, 
rather than drawing a line as it usually would, it moves the sprite along 
with it on the screen. To take it a step further, you can move several 
sprites apparently at the same time by telling the turtle to take turns 
jumping from one sprite to the next, moving each a little bit on each turn.  

The use of sprites is discussed in great detail in the section of this 
document entitled "Sprites".  

JUMP - goto a destination

       J: label
       J: #variable
       J: @A
       J: @P
       J: @-P
       J: @M

Unless otherwise instructed, PILOT executes each statement in your program 
one after the other, in the exact order that the statements are written. With 
the JUMP statement you can alter this order by branching to a specified 
location. The location can be a statement label, a numeric variable, or one 
of four possible special destinations which are commonly needed.  

JUMP TO A LABEL

The first form of the JUMP statement above transfers control to the statement 
following the specified label. Although the statement label in the program is 
preceded by an "*", you do not put the "*" character on the JUMP statement.  

EXAMPLE 1: jump to a label

       J:PART4
       . . .
      *PART4 T:This is chapter 4.

If the label name to which the program should jump is contained in a string 
variable, use the Execute Indirect statement to perform the jump as shown in 
this example.  

EXAMPLE 2: jump to a string variable, say X$:

       X:"J:" !! X$

or if the jump is to be conditional:

       X(condition):"J:" !! X$

JUMP TO A NUMERIC VARIABLE

The second format shown above permits a jump to a location stored in a 
numeric variable. This is a special purpose use which can be used in only one 
way. The numeric variable used in the Jump can be set by the statement: 

       C: X = %E

which sets variable X to the jump location of the return point from the most 
recent Use statement. Then to jump to this location use: 

       J: #X

This special case Jump is used only in the construction of an Escape routine 
which links to another module then expects to return to the point from which 
the escape routine was called.  


JUMP TO LAST ACCEPT STATEMENT

The third form of the JUMP shown above is used to branch back to the last 
ACCEPT statement that was executed. This is useful to allow the student to 
re-answer the question just answered.  

EXAMPLE 3: jump to last ACCEPT

       T:What is 2+3?
       A:
       M:5
       TY:Right
       TN:No, try again
       JN:@A


JUMP TO THE NEXT MATCH

When a student response is evaluated, there is sometimes a series of MATCH 
commands to test for various correct and incorrect possibilities.  After each 
MATCH might be a series of statements to be executed if the MATCH is YES. 
Otherwise it is convenient to jump directly to the next MATCH to check for 
the next possibility.  

EXAMPLE 4: jump to next MATCH

       M:calcium
       JN:@M
       . . . 
       M:silicon
       JN:@M
       . . . 
       M: . . .


JUMP TO NEXT PROBLEM

If a program consists of a set of questions or problems, presented one after 
the other, it can be convenient to start each question section with the P: 
statement. Then, from anywhere within the previous question, the program can 
branch to the next problem without having to place a label on each question.  

EXAMPLE 5: jump to next problem

       M:Italy
       TY:Right, let's go on.
       JY:@P
       . . .
       P:
       T:Question 14.
       T:...
   

JUMP TO LAST PROBLEM

The final format of the Jump permits the program to jump back to the last 
Problem statement passed. This could be useful in going back to the start of 
the current section or when going back to accept another answer when the 
cursor must be positioned prior to letting the student answer again.  

EXAMPLE 6: jump to last Problem

       P:
       TS:G10,5;F4;B1
       A:
       . . .
       J:@-P

See also:  STATEMENT LABELS


KEEP RECORDS - save data on disk

       K: expression

The KEEP statement  provides a simple way to write data to a disk file for 
later manipulation. It can be used to store student progress records, scores, 
remarks from the student to the author, student answers, etc. The file 
written by the KEEP statement is a text file which can be displayed by the 
DOS TYPE command or examined by a text editor, such as EZ. It can also be 
read by another program to perform statistics or other reporting.  

The default file name used to store data written by the KEEP statement is 
K.REC, but the K option of the PROBLEM statement can be used to specify any 
filename, pathname, or network file name to be used instead. You need not 
take any action to create the keep file prior to running the PILOT program. 
If it does not exist, the KEEP statement automatically creates the file.  

Each time the KEEP statement is executed, the string value of the expression 
after the colon is written to the current keep file.  A new-line sequence is 
appended to the string expression as it is written to the file. This means 
that each KEEP adds one text line to the keep file.  

The keep file continues to grow until it is explicitly erased by a DOS 
command.  

EXAMPLE 1: save student name and score

       T:Well, $NAME$ , you got #SCORE right.
       K: NAME$ !! SCORE
       E:


See also: PROBLEM

LINK - chain to another program file


       L: filename
       L: filename, destination

Most programs you write should be divided into separate files, or modules. 
This facilitates program editing and helps keep an organized structure to 
your program. The LINK statement is used to transfer control from one program 
module to another.  LINK is similar in use to the CHAIN statement of BASIC. 
When LINK is executed, the current program is removed from memory and the 
linked program is loaded into memory.  All variables are retained from one 
module to the next. If you wish to Link to a string variable, see example 3 
below.  

EXAMPLE 1: link to another program file

       L:CHAPTER7

In the above, the program is assumed to be in file CHAPTER7.PIL.  

With LINK you can start the new module at the beginning or at any label 
within the module.  

EXAMPLE 2: link to a label in another file

       L:CHEMX,Q3

The above links to file CHEMX.PIL, then does an automatic JUMP to label Q3 in 
that file.  

EXAMPLE 3: link to file name in a string variable, say X$ 

       X:"L:" !! X$

See also: JUMP

MATCH - compare student response

       M:pattern
       MS:pattern
       MJ:pattern
       MX:expression

MATCH is used to test the answer given by the student to a previous ACCEPT 
statement. There are two types of MATCH, pattern matching and numerical 
matching. In either case, the result of the MATCH is a YES or a NO. The YES 
or NO can subsequently be tested by use of the Y or N conditionals.  

PILOT does not make any assumptions about the correctness or incorrectness of 
an answer. You can use MATCH equally well to test for correct answers or 
anticipated incorrect answers. YES does not necessarily always mean correct 
and NO does not necessarily always mean incorrect.  

PATTERN MATCHING

MATCH compares the student answer buffer (%B) with the pattern after the 
colon on the MATCH statement.  The result is a YES or NO match which can be 
tested by the Y or N conditionals.  When comparing, if the student answer 
contains the match pattern anywhere within the student answer, it is 
considered a YES match.  

EXAMPLE 1: simple MATCH

       M:HAT
                student answer: CHATTER gives YES
                student answer: HAT gives YES
                student answer: CAT gives NO

SPECIAL MATCH CHARACTERS

When writing the pattern, you can use the following special characters within 
the pattern.  

*    matches any one character

&    matches any string of zero or more characters  

It can be considered to separate several items which must occur in specific 
order but that may have other data between items.  

@    separate items which must be present but may be in 
         any order  

!      separate alternative patterns

%    matches only a space or the start or end of the answer 
 

NEGATION

If the first character of the match pattern is the not character, "^" , then 
the sense of the match is inverted. That is, it will yield a YES if the match 
pattern is NOT found in the student answer, and will yield a NO if the match 
pattern IS found in the student answer.  


SPELLING ERRORS

The S modifier can be appended to the MATCH op code.  MS: is sometimes called 
MATCH SPELLING.  The Spelling modifier makes the MATCH more liberal in its 
comparison. If the student answer is off by only a minor spelling error, then 
the MATCH is still YES. A minor spelling error is one wrong letter or two 
inverted letters.  

EXAMPLE 2: Various MATCH statements.
                
M:HAT
                          HAT - YES
                          CHATTER - YES

M:%HAT%
                          HAT - YES
                          CHATTER - NO

M:CAT&DOG
                          CATDOG - YES
                          CATS AND DOGS - YES
                          DOGS AND CATS - NO

M:CAT@DOG
                          CATDOG - YES
                          CATS AND DOGS - YES
                          DOGS AND CATS - YES

MS:GREEN
                          GREAN - YES
                          GRENE - YES    

MS:CAT!DOG
                          CAT - YES
                          COT - YES
                          DIG - YES

M:H*T
                          HOT - YES
                          HAT - YES
                          HT - NO
 
M:^DOG
                          DOG - NO
                          CAT - YES

M:RED&BLUE!HOT
                          RED, WHITE, BLUE - YES
                          HOT - YES
                          RED - NO

SYSTEM VARIABLES AFTER A MATCH

There are three system variables set after a pattern match. Each is set to 
zero if the pattern did not match, otherwise each is set as follows:  

%N  -  alternate answer indicator

%N is the number of the alternate answer which matched when an "!" is used to 
separate possible alternate answers.  For example, M:CAT!DOG!HORSE if the 
student types CAT, %N=1, if the student types DOG, %N=2, etc.  

%M  -  offset of match in student answer

%M is the byte location within the student answer (ie.  subscript within %B) 
at which the match began.  

%L  -  match length

%L is the number of bytes within the student answer (%B) which matched.  

Example: 

       M:C&T

If student reply is SCANTY, 

       %M=2, %L=4 

AUTOMATIC JUMP TO NEXT MATCH 

Appending the J modifier to the MATCH op code causes a JUMP to the next MATCH 
if this match results in a NO.  

NUMERIC MATCH

The MX: statement is used to make numeric comparisons. The argument after the 
colon is an expression. The expression is evaluated, if the numeric value of 
the expression is true (non-zero), the result of the MATCH is YES. If the 
numeric value of the expression is false (0), then the result of the MATCH is 
NO.  

EXAMPLE 3: numeric matching

        MX: FLO(%B) > 50
        TY:Too big, try again.

        MX: X > 98.3  &  X < 98.9
        TY:Close enough.

See also:  ACCEPT, JUMP, CONDITIONALS

NEW CHARACTER - define char pattern

       N:c . . . / / /       (64 . and / characters)

PILOT uses Ascii character codes 32 through 256 for printable characters. The 
ASCII code table defines only the characters from 32 through 127.  This 
leaves 128 characters, from 128 to 256, for other uses. These characters are 
used in the text modes (modes 0 through 3) for the extended text mode 
characters. These include various line drawing characters, mathematical 
symbols and foreign characters. In the graphics modes (modes 4 through 6) the 
128 extra characters are set aside as user-definable special characters. This 
means that you can design your own characters for special type fonts, foreign 
languages, or other special symbols.  

The special characters should not be confused with character "fonts". Special 
characters defined by the N: statement are restricted to the standard 8 by 8 
pixel character size. Character fonts, described under the NS: statement, can 
be used for smaller or larger character representations.  

The NEW CHARACTER command can be used to change the 8 by 8 dot pattern for 
any of the 128 changeable characters. Prior to execution of any N: statement 
the characters from 128 to 255 have unpredictable display patterns in the 
graphics modes.  Once at least one N: statement has been executed, the 
characters from 128 to 255 that have not been explicitly changed will have 
the same display pattern as the corresponding character in the range 0 to 
127.  The N: statement has no effect on the characters displayed in text 
modes. In text modes, the characters displayed are always the default text 
mode extended character set, as shown in Appendix B.  

The letter c shown in the format of N: above stands for any character from 
128 to 255. (The EZ editor provides a way to enter characters in that range 
into a program.)  It is followed by 64 periods and slash characters.  They 
depict the pattern of zero (.) and one (/) bits that will be used to display 
the character.  The 64 bits may be given on 8 lines of 8 bits each, to give a 
visual picture of the character pattern.  The 64 bits may also be given all 
on one line or any desired format that adds up to 64.  Intervening spaces and 
new lines are ignored.  


CHARACTER EDITOR

Although you could write an N: statement and manually determine the pattern 
of dots and slashes, you would normally use the Character Editor included in 
the EZ editor. It makes the process of creating character patterns very easy. 
EZ also allows you to see your re-defined characters while you are editing 
your program if you wish.  

See also: The EZ Editor 

NEW HEIGHT/WIDTH - set font size


       NH: h,w

The NH: statement may be used to change the default font character cell size. 
The font character cell size is used to compute row/column coordinates for 
cursor addressing by the "TS:Gc,r" command when in font display mode.  

When a font is activated as the current font (see NS: statement) it has a 
default character cell height and width, in pixels. This default height and 
width are usually set to accommodate the largest character in the font. When 
the program executes a TYPE SCREEN with a GOTO command to set the cursor, the 
character cell height and width are used to compute the pixel location for 
the cursor.  

A typical use of NH: is to set both height and width to 1. Thus the command 
to set the cursor location has the effect of absolute pixel addressing. Thus 
a font character could be written at any pixel on the screen.  

EXAMPLE 1: change to pixel addressing

       NH: 1,1

See also: NEW FONT

NEW FONT - set font mode

 
       NS: variable$
       NS: variable$,c1,c2,c3
       NS:

The NS: statement may be used to set "font display mode". NS: may be executed 
only with the screen in display mode 4 or higher. The "variable$" must be a 
character string variable which contains the desired character font. In font 
display mode all characters typed by the program or entered on the keyboard 
are displayed in the type size and style of the active character font.  

Character fonts can be used to display text in characters that range in size 
up to 24 by 24 pixels, and accommodate an unlimited variety of type styles.  

The character font may be one supplied with PILOT or may be one created by 
using the Font Editor, described in a later section of this document.  

The NS: statement with no parameters after the colon may be used to turn off 
font display mode and return to normal text display mode. Font display mode 
is also turned off by the mode set command of the TYPE SCREEN statement.  

When font display mode is entered the font text cursor is placed in the home 
position and color and spacing options are set to the defaults contained in 
the font.  


FONT COLORS 

A character font can define each character in one, two or three colors. So an 
individual character can contain as many as three different colored pixels.  
This provides for great flexibility in font design for outlines, drop 
shadows, etc.  The three colors are numbered 1,2 and 3. Some fonts are 
designed with one color only. In this case the one color is normally color 3.  

The NS: statement provides for a way to re-map the three colors to any other 
three colors. In modes 4 and 5 the three new colors can be from 0 to 3. But 
in EGA extended modes (13,14 and 16) the three new colors can be selected 
from 0 through 15. So at any one time a character can be displayed in up to 
three of the colors supported in the current screen mode.  

To re-map the colors use the second form of the NS: statement above. The 
values for c1,c2 and c3 are the new color numbers for the three colors.  

The foreground color command of the TYPE SCREEN statement and the #n command 
of the TYPE statement both provide a means of changing the text color. Both 
of these commands set the new value for color number 3 of the font. So for 
fonts which are defined in one color, the same commands used when not in font 
display mode are used to set the text color in font display mode as well.  


HOW TO READ A FONT

To use a font the program must first set up a string variable long enough to 
contain the font, and must read the font file into the string variable. By 
convention, PILOT font files have a file name suffix of ".PIF". The following 
example shows how to read a font file into a string variable.  

EXAMPLE 1: read a font file

       D: F$(5000)
       FX: HELV9.PIF
       FI: 0,F$


FONT CURSOR ADDRESSING

Characters are displayed in font mode with proportional spacing. This means 
that each character is only as wide as necessary. Also, a character can be 
displayed at any pixel boundary, not only at the pre-defined character cells 
of normal text. When in font display mode the text cursor is kept in terms of 
pixels, not character cells. The cursor is considered to be at the upper left 
pixel of the cell in which the next character would be displayed. The XCR and 
YCR functions return pixel values in this mode.  

Viewports can be used with font display mode, but the viewport boundaries are 
still expressed in the character boundaries used for non-font mode. The 
result is that viewports are always defined on 8 pixel boundaries though the 
characters in the viewport might be displayed at any pixel. Cursor addressing 
within a viewport is relative to the home pixel of the viewport (upper left 
pixel).  

Proportional spacing improves readability and permits more text per line but 
it somewhat complicates the issue of cursor row/column addressing.  The GOTO 
command of the TS: statement may be used to move the cursor to any screen 
position by specifying a row and column coordinate. Since each character is 
different size, each font has a default character cell height and width 
defined. These values usually represent average character size for the font. 
These average sizes are used to position the font text cursor. The cursor is 
positioned at the pixel represented by the column and row values multiplied 
by the default character cell size.  

The NH: statement provides a means of altering the effect of cursor 
addressing. With NH: the program can change the values multiplied by the row 
and column numbers. The most typical case is to execute the statement  NH:1,1  
after executing the NS: statement.  This sets cursor addressing to pixel 
coordinates giving the program the ability to address the font text cursor to 
an absolute pixel.  

