Chapter 3. OPERATORS AND EXPRESSIONS

PILOT accepts expressions in many contexts.  An expression is a combination 
of variables, numeric constants, string constants, functions and operators.  
Expressions are formed in the normal manner allowed by other programming 
languages.  Operator precedence is similar to that of basic.  Parentheses may 
be used to group subexpressions.  

EXAMPLE: simple expressions

       X + 5
       SIN(I)
       2.5
       (A + B) <= (C + D)


DATA TYPES

Each element of an expression is a number or a string value.  Numbers are 
stored in floating point form with an accuracy of about 6 decimal digits.  
Strings are stored in variable length form with a terminating null character.  

Each operator or function expects to act on a particular type of argument, 
and in return produces a particular type of result.  For example, + expects 
two numeric arguments and it produces a numeric result. A unique and 
convenient feature of PILOT is auto-type conversion.  This means that any 
time an argument is of the wrong type (string or number) it is automatically 
converted to the correct type for the context.  A number is converted to a 
string in a manner like that of the STR function, which puts the value in 
printable format with decimal places only if necessary.  A string is 
converted to a number in a manner like that of the FLO function, which scans 
the string for the first number value or returns zero if no number is found.  
VARIABLES 

A variable name can be up to length six.   The first character must be a 
letter.  Other characters may be letters or digits.  The last character may 
be a $ to signify a string variable.  Upper and lower case letters are 
considered to be equal when naming a variable (i.e. - XYZ and xyz name the 
same variable).  A string variable must be dimensioned in a D: statement 
before it can be used to store a string value.  

EXAMPLE: variables

      X  COUNT  J5  able  NAME$ 

SYSTEM VARIABLES

There are several system variables which can be used in the same context as 
other variables.  

%A - answer counter

%A is a numeric variable equal to the number of times the last A: has 
executed without any other intervening A:. It tells how many attempts the 
student has made on this question.  

%B - answer buffer

%B is a string variable which is set to the response given by the student on 
each A:. %B has a maximum length of 80 characters. It can be subscripted like 
any string variable.  

%E - return point of last U:

%E is a numeric variable which returns the jump value of the return point of 
the most recent USE statement. It is the location which would be returned to 
via an END statement.  

%N %M %L - match result variables 

These are parsing variables which return information about the last MATCH. 
See the MATCH statement for more details.  

See also:  COMPUTE, DIMENSION, SUBSCRIPTING

SUBSCRIPTING

       array  (position)
       strng$ (position)
       strng$ (position, length)

SUBSCRIPTS are used to select an individual value out of a numeric array or a 
substring out of a string variable.  Subscripts consist of a position and 
possibly a length, enclosed in parentheses after a variable name. The 
position and length values can be expressions. Before subscripts can be used 
the variable must have been dimensioned.  See the DIMENSION statement for 
more information.  

NUMERIC ARRAY SUBSCRIPTING

Numeric arrays start at subscript zero and end at the dimensioned size.  An 
attempt to subscript beyond the array limit results in an error message. A 
reference to an array name without subscripts results in a reference to item 
number zero of the array.  

EXAMPLE 1: array subscripts

       C: A(3) = X
       C: A(I) = A(I) + 1
       C: LIST(J) = A * 5

STRING SUBSCRIPTING

String subscripts start at one. If you specify a starting position less than 
one, PILOT will assume you meant one. If you omit the length, a length of one 
is assumed. The portion of a string picked out by subscripts is sometimes 
called a substring.  


EXAMPLE 2: simple string subscripts

       D: X$(20), Y$(10)
       C: X$ = "ABCDEFGHIJKLMNOP"
       C: Y$ = X$(3)
                          Y$ is now equal to "C"
       C: Y$ = X$(5,4)
                          Y$ is now equal to "EFGH"
  
You can assign a value into a substring by placing the subscripted string 
variable on the left hand side of a COMPUTE statement. In this case, only the 
characters within the substring are modified. All other characters within the 
string are unchanged.  

EXAMPLE 3: assignment to a substring

       D: X$(20)
       C: X$ = "ABCDEFGH"
       C: X$(3) = "s"
                          X$ is now equal to "ABsDEFGH"
       C: X$(4,3) = "12345"
                          X$ is now equal to "ABs123GH"
       C: X$(4,3) = "xy"
                          X$ is now equal to "ABsxy GH"

Since a string variable can contain a variable number of characters at any 
one time, it is possible that its current length is less than its maximum 
length as set up by the DIMENSION statement.  

If, when a subscripted string is not the target of a COMPUTE statement, the 
start subscript is over the end of the current string length, the returned 
value is a null string. If the start subscript is within the string but the 
length would run over the string length then only the remaining characters 
are returned.  


EXAMPLE 4: padding a string to its max length

       D: X$(100)
       C: X$(100) = " "
                          X$ is now equal to 100 spaces
    

You can access a substring of any length you wish. If you leave off the 
length, then the substring is assumed to be length 1. If you give a length 
that would go past the current end of the string, then the substring goes 
from the starting position you specified to the current end of the string. So 
by using a large length value you can reference a substring starting at a 
given position and containing the rest of the string. This is similar to the 
RIGHT function in some languages.  

EXAMPLE 5: the rest of the string 

       C: X$ = "ABCDEFGHIJ"
       C: Y$ = X$(3,20)
                          Y$ is now equal to "CDEFGHIJ"

See also:  DIMENSION, VARIABLES

NUMERIC CONSTANTS

       [-]digits
       [-]digits.digits

A numeric constant consists of an optional leading minus sign, a string of 
decimal digits optionally including a decimal point. Numbers are retained to 
about six digits of accuracy.  

EXAMPLE: numeric constants

       5
       63.789
       -42.1

STRING CONSTANTS

       "text"

A string constant, or literal, consists of zero or more characters enclosed 
in quotes.  

EXAMPLE:

       A$="BANANA"
       T(X$ < "A"): NO SIR.

OPERATORS


ARITHMETIC

       x + y       x - y       x * y       x / y
       x % y  (remainder of x/y)        -x

To compute A to the B power use EXP(B*LNE(A)) 


RELATIONAL

       x < y     x > y     x = y     x <> y
       x <= y    x >= y

Comparison is numeric if x is a number or string if x is a string.  For 
string comparisons the shorter string is padded on the right with spaces for 
comparison purposes.  Relational operators always yield a one for true or a 
zero for false.  


LOGICAL

       x & y         (true if both x and y are non-zero)
       x ! y          (true if either x or y is non-zero)
       ^x or ~x     (true if x is zero)

Logical operators always produce a 1 for true or a zero for false.  


STRING

       x$ !! y$       (concatenation)

Concatenation produces a string consisting of the string value of y$ appended 
to the right end of the string value of x$.  FUNCTIONS 


A built-in function can be used in an expression to return a pre-defined 
computation or value.  The function name is always followed by parentheses 
containing one or more function arguments. The function arguments may be 
expressions.  

ABS(X) - the positive value of X ABS(9) is 9, ABS(-9) is 9 

ASC(X$) - the numeric value 0-255 of char X$, ASC("A")=65 

ATN(X) - arctangent in degrees of X, ATN(1) is 45 

AUX(0) - reads the com1: (rs232) port

Returns CHR(0) if no byte ready to read, or a character from CHR(1) to 
CHR(255).The com1: port must be set up via a DOS MODE command before entering 
PILOT.  

CAP(X$) - the upper case value of string X$

CAP("X2 is it.") is "X2 IS IT". 

COS(X) - cosine of X degrees, COS(60) is .5

CHR(X) - the Xth ascii character, CHR(65) is A 

CLK(n) - time and date clock

n=0 gives the time of day in seconds, n=1 gives year; n=2 gives month; n=3 
gives day 

DEC(X,n) - string value of number X with n decimal places 

DEC(13.45095,2) is 13.45 

EXP(X) - e to the X power,  EXP(3.5) is 33.11 ...

FIZ(X$) - size of a file

X$ MUST BE a string variable, NOT an expression. The variable contains a path 
or file name. The return value is the length, in bytes, of the file, or -1 if 
the  file does not exist.  

FLO(X$) - convert a string to a real number

The numeric value of the first number found in string X$, FLO("Either 12 or 
14") is 12. 

INS(X$) - search for a character in %b

Returns zero if character X$ is not in %B, otherwise the first 
position in %B where X$ is found. 

INP(X) - machine level IN instruction

Returns a byte from io port X. 

INT(X) - value of X truncated to an integer, INT(13.89) is 13 

KEY(X) - return keyboard status

Returns zero if no key is pressed,  otherwise the ascii code for the 
depressed key.  If X=0, then the character is read from the type-ahead 
buffer.  If X=1, then the character is left in the type ahead buffer.  

LEN(X$) - current length of string X$, LEN("abc") is 3 

LNE(X) - natural log (base e) of X, LNE(10) is 2.302 ...

LOG(X) - log base 10 of X, LOG(10) is 1.00

MEM(0) - number of unused bytes for strings and arrays 

MOD(0) - returns the current screen mode 

OFF(X$) - memory offset address

Returns the offset part of the address of the string variable. 

PEK(X) - read memory byte

Returns a value from 0 to 255 equal to the byte in memory at offset X in the 
segment whose base is in the variable %A.  RND(X) - random number generator 

If X is zero, returns a random   fraction from 0 to 1. If X>0, returns a 
random integer from 0 to X-1. If X=-1, a fixed sequence of random numbers is 
used for all subsequent uses of RND and SFL.  

RSP(X$) - the string value of X$ with all spaces removed, 

RSP("That is all") is "Thatisall".

SEG(X$) - memory segment address

Returns the segment part of the address of the string variable.  

SFL(X$) - shuffled version of the characters in string X$, 

SFL("abcde") might be "bcade".

SGN(X) - -1 if X is negative, 0 if X is 0, +1 if X is positive 

SIN(X) - sine of X degrees, SIN(30) is .5

SPC(n) - gives n spaces

SQR(X) - square root of X, SQR(9) is 3

STR(X) - the string value of number X

SWP("xy") - swap characters

Returns a string equal to the value of %B except that each character x is 
changed to character y; if %B holds "Why not exit?", SWP("xy") is Why not 
eyit?  

TIM(0) - response time in seconds of last A:

TSP(X$) - string value of X$ with trailing spaces removed 

WRD(X$,n) - gives the nth word in the string X$ 

WRD("one two three four",2) returns "two" 

XCR(0) - x position of the text cursor

XPX(0) - x position of the graphic turtle

YCR(0) - y position of the text cursor

YPX(0) - y position of the graphic turtle

EXAMPLE 1: use AUX to read N characters from serial port 

       D:X$(80)
       C:X$ = ""
       C:N=10
       *LOOP  C:X$= X$ !! AUX(0)
       J(LEN(X$)<N):LOOP

EXAMPLE 2: use CLK to print date and time of day 

       C: T = CLK(0)
       C: HH = INT(T/3600)
       C: MM = INT((T-3600*HH)/60)
       C: SS = INT(T-HH*3600 - MM*60)
       C: YY = CLK(1) ; MO = CLK(2) ; DD = CLK(3)
       T: #YY/#MO/#DD   #HH:#MM:#SS

EXAMPLE 3: use SFL to randomize a list of 10 questions 

       D: X$(10)
       C: X$ = "ABCDEFGHIJ"
       C: X$ = SFL(X$)
       C: N=0
       R: each problem ends by a JUMP to LOOP
       *LOOP
       C: N=N+1
       J(N>10):DONE
       X: "J:QUES" !! X$(N)
       . . .
       *QUESA . . .
       . . .
       J:LOOP


Chapter 4. GOTO AND ESCAPE COMMANDS

GOTO COMMAND

The GOTO command can be enabled or disabled by an option on the PROBLEM 
statement. If enabled, then each ACCEPT statement automatically checks the 
student response for the command: 

       GOTO destination

If present, a JUMP to the destination is immediately performed. The 
destination can be any of those available on the JUMP statement.  This 
feature is extremely useful when writing or debugging a long program. You can 
enable the GOTO option, then when testing, you can jump around in the program 
to test the relevant section. Once the program is debugged, you can disable 
the GOTO command.  

You could conceivably allow the student to use GOTO to navigate within a 
program, however, there is a better way to give the student the branching 
control needed.  


ESCAPE COMMAND

The ESCAPE command can be enabled or disabled by two options on the PROBLEM 
statement, the E option enables the ESCAPE key, and the F option enables the 
FUNCTION and CURSOR keys. You can choose to have either, both or neither 
option enabled. The enabled keys become "HOT KEYS" that cause an immediate 
action to take place if the student presses the key while responding to an 
ACCEPT. If one of the (enabled) hot keys is detected the automatic action is 
equivalent to: 

       U: SYSX

That is, the subroutine named *SYSX is called.  It is up to you to insure 
that the label *SYSX is present in the program module and that it contains 
the code to perform the desired special action.  

The SYSX routine can be used to record comments from the student as shown in 
the first example below.  It can also be used to allow the display of a menu 
or glossary on demand.  The SYSX routine should end with an END statement.  
If no argument is given on the END then a return is made to the statement 
after the ACCEPT.  The first example below returns to re-execute the ACCEPT.  
Note also that since the END can specify a label, it is not necessary to 
return at all, as shown in the second example.  


EXAMPLE 1: SYSX used to record student comments. If the student enters a 
comment, then the ESCAPE key, the comment is written to the KEEP file.  

       *SYSX  K:%B
       E:@A

EXAMPLE 2: SYSX used to return to a main menu 

       *SYSX  T: GOING TO MAIN MENU.
       E:MENU

EXAMPLE 3: SYSX used to display a help page, then return to allow the student 
to answer again.  

       *SYSX
       GSX:                            (save screen image)
       U:HELP                        (go display the help)
       T:Push a key to go on.
       W:30000                       (pause while he reads)
       GX:                             (put the screen back)
       E:@A                           (return to ACCEPT)
 
ANSWER BUFFER DURING AN ESCAPE

When the SYSX routine is reached, the last character in the answer buffer, 
%B, is the character that caused the escape function to take place. If the 
student had entered any data prior to pushing the hot key, then that data is 
also in %B, as usual. This example shows how to separate the last character 
from %B.  

EXAMPLE 4: SYSX used detect which hot key used

       *SYSX
       C: L = LEN(%B)                        (length of %B)
       C: K = ASC(%B(L))                   (K is hot key value)
       C(L>1): %B = %B(1,L-1)           (remove last char)
      

CHANGING THE ESCAPE KEYS

The P:E option enables the ESC key. It generates ASCII code 27. If you wish 
to use another key for this purpose use the NX: statement to change which key 
generates code 27.  

Similarly, P:F enables codes 187 through 221.  These are the codes normally 
generated by the function keys, the shifted function keys, and the keys in 
the cursor control pad area. You could re-assign various keys in and out of 
this range to control which keys are hot keys.  

COMPATIBILITY

For compatibility with other versions of PILOT.  The P:E option also enables 
the escape to *SYSX if the first character of a student reply is the "@" 
character. This check takes place only after the student has pushed the ENTER 
key to end the response.  

See also:  PROBLEM, ACCEPT, USE, END   

Chapter 5. ERROR MESSAGES

PILOT is programming-error tolerant. If an error is detected, the statement 
in error is displayed. Before it is a message which identifies the problem.  
Execution then pauses.  The user can push ctrl-c to stop the program or push 
any other key to ignore the error and continue execution with the next 
statement.  If it is at all possible to go on, and it usually is, PILOT will 
continue with the program.  The following error codes are used by PILOT.  
Error messages can be suppressed by setting the I option on the PROBLEM 
statement.  

disk - i/o error in program file 

This usually means that the diskette has unreadable data on it.  
      
exp - invalid or missing expression 

This error can signify any number of syntax errors in the construction of a 
PILOT statement. Usually it means that you have used operators or functions 
improperly.  

file - no file open or disk i/o error 

This error can mean that a diskette is write-protected, full, or the 
directory is full. It can also mean that the FILES=n parameter in your 
CONFIG.SYS file specifies too few files for your system. Try placing  
FILES=16  in your file CONFIG.SYS. 

label - missing destination 

A syntax error in specifying a jump label.  

link - program file not found (program stops) 

You linked to a file or path name that could not be found.  

lspace - too many labels in one program module 

One program module can contain 200 labels. Break the module into several 
smaller ones.  mode - graphics done when not in mode 4, 5 or 6. The hardware 
will not do graphics in a text mode.  

open - can not open disk file 

Disk drive not ready, write protected, or full. See also "file" above 

opcode - invalid op code or modifiers 

PILOT does not recognize what comes before the colon as a legal statement.  

paren - missing parenthesis

quote - missing closing quote

sprite - illegal sprite syntax 

Attempt to use a string less than 2218 bytes as a sprite table, or invalid 
sprite usage.  

sspace - memory overflow

Not enough string and array space left to do string operations.  

subscript - too  big for the array 

syntax - statement has bad command or operator

uspace - use call level is too deep ( over 32 )

var - missing variable name

vspace - over 200 variables in use

xspace - no more memory for arrays or strings


Chapter 6. DISTRIBUTING PROGRAMS

If you develop a program using PILOT and wish to provide that program to 
others who may not have PILOT, you can do so by following these procedures.  

First, develop and test your program in the normal way.  Next, use the PCRYPT 
program to translate your lesson files into a binary format which is not 
human-readable.  To do this type 

       PCRYPT  name  n

n is a number which represents the maximum program length in 8KB increments. 
If n is omitted, PCRYPT defaults to a value of 4 (32 KB).  This command reads 
your program from file name.PIL and produces a file named name.PIX.  It is 
impossible to go backwards from a PIX file to a PIL file, so be sure to keep 
the original.  If your lesson uses LINK statements you must use PCRYPT to 
translate all applicable lesson files. The following command can be used to 
encrypt all PIL files in the current disk or directory: 

       PCRYPT  *  n  

To run the encrypted (.PIX) version of a program use: 

       CPI  name  n

To distribute your program provide the PIX files and the file CPI.EXE to the 
user.  The user can run the program but can neither read nor modify your 
source code. 

Do not duplicate or distribute copies of any other files provided with the 
PILOT system.  


Chapter 7. EZ EDITOR
                                                            
EZ is a full screen text editor.  You can use it to create and edit your 
PILOT programs. To use it enter: 

       EZ  name.PIL
                   
where name.PIL is the file name you wish to create or modify.  If the file 
does not exist, it is created.  If it does exist, it is read into memory and 
displayed on the screen.  When you finish with EZ, a backup copy of the file 
is retained as name.BAK. You always have two copies of your program file: 
name.PIL is the current copy and name.BAK is the file just prior to the last 
time you edited the file. The EZ command and file name may be preceded by 
optional drive or path designations per normal DOS conventions. The maximum 
size text file supported by EZ is 50,000 bytes.  


EZ FUNCTION KEYS

Once in EZ, the screen is a window on the text file.  The various cursor and 
function keys are used to move around in the text and to add, change or 
delete text.  When adding or replacing text, you just type on the keyboard; 
what you see on the screen is what you get in the text file.  The following 
summary shows the various keyboard functions you can use. The F9 key may be 
used at any time to display an on-line help menu which summarizes these 
functions.  


Arrows - move the cursor one space in any direction  

TAB - skip to next tab stop. Tab stops are each 10 columns  

HOME - move to the first text line of the file  

END - move to the last text line of the file  

PG UP - move up (backwards) one screen  

PG DN - move down (forward) one screen  
INS - insert a space into the line  

DEL - remove the current character  

F1 - insert line

When in column 1: Insert a blank line.  When not in column 1: Split line into 
two lines.  

F2 - delete line

When in column 1: Remove the current line and place it on the PICK STACK.  
When at end of a line: join the next line to the current line.  

F3 - copy the current line onto the PICK STACK  

F4 - insert top line off the PICK STACK before current line  

F5 - search string, or goto a line number,  see below   

shift F5 - replace search string, see below  

F6 - shift to extended character set for next key pressed  

shift F6 - shift lock to extended character set

Shift until F6 pushed again or the ENTER key is pushed.  This enables  the 
insertion of characters from 128-255 into a program file.  See appendix B for 
available characters.  

F7 - expand a MACRO into the text  

shift F7 - insert a file into the text

Enter the name of a file to be copied into the current file and inserted 
prior to the current line.  

F8 - switches to/from graphics mode 

In graphics mode characters defined by N: statements in this program  file 
are displayed.  User can enter name of another PILOT file which has further 
N: statements to be executed.  

shift F8 - enter character editor (only in graphics mode)

F9 - on-line HELP key  

shift F9 - write or print all or part of text

Write all or a part of the text to a disk file or to the printer. To send the 
text to the system printer enter PRN: as the file name.  

To start the write at a line other than the first line of the file, place a 
line containing only [[[[ prior to the first line to be written. To stop 
writing prior to the end of the file place a line containing only ]]]] after 
the last line to be written.    

F10 - save file and exit to DOS  

shift-F10 - abandon edited file, exit to DOS without saving

USING THE PICK STACK IN EZ

The PICK STACK is an invisible last-in/first-out buffer which can store up to 
16 lines of text at a time.  It has three uses.  

First, if you accidentally delete some lines using F2, they can be put back 
again by pushing F4.  

Second, to move lines push F2 once per line to delete them, then move to the 
desired location and push F4 once per line to re-insert them in the new 
place.  

Third, to duplicate lines push F3 once per line to copy them onto the PICK 
STACK, then move to the new location and push F4 once per line to insert them 
in the new place.  

SEARCH AND REPLACE

To search for a line number push F5 then press the "@" key, the line number, 
and ENTER.  

To search for a string push F5 then type the string and push ENTER. To find 
the same string again just push F5 then ENTER, you do not need to type the 
search string again if it is the same as the last search.  

To search for a string and replace it with another string: push F5, then type 
the search string (but don't push ENTER yet). Next push shift-F5, then type 
the replacement string and push ENTER. EZ will find and display the next 
occurrence of the search string.  At that time push shift-F5 to replace the 
string, or just push F5 to find the next occurrence. By using F5 and shift-F5 
alternately you can see each occurrence of the search string to decide 
whether it should be replaced.  

To find each successive occurrence of the search string and immediately 
replace it with the replacement string, just push shift-F5.  repeatedly, once 
for each time you wish to search and replace.  

MACROS IN EZ

The F7 key is used to read and expand a macro into the text. A macro is a 
pre-programmed sequence of instructions which can be accessed as a whole to 
reduce your programming time. To include a macro push F7 then type the name 
of the macro file and push ENTER. The macro may prompt for information on the 
bottom two lines of the screen prior to completing the macro expansion. More 
information on macros can be found below. See "How to Write a Macro for EZ".  

EXTENDED CHARACTERS IN EZ

The extended characters, from ASCII 128 to 255, do not have keys on the 
keyboard. By using the F6 key you can enter these extended characters.  To 
enter one, push F6, then another key. A value of 128 is added to the normal 
value of the key, which produces a character in the extended range. Appendix 
A contains a list of the numeric values for the various keyboard 
combinations.  The character editor, described below, can also be used to 
determine the key combination for any particular extended character.  

When EZ is entered, the screen is in text mode.  In this mode you see the 
text mode extended characters for codes 128 to 255. These are the characters 
built-in to the hardware which would appear in a PILOT program for text modes 
(0-3).  

The F8 key switches EZ to graphics mode. In this mode you see the user-
defined characters for codes 128 to 255.  

The PILOT N: statement allows you to redefine character patterns to be 
displayed when the PILOT program in executed. The F8 key allows you to see 
the re-defined characters while editing your program with EZ.  

When F8 is pushed, all N: statements in the file are executed, just as they 
will be executed when the PILOT program is run. Also, you are prompted for 
the name of another file which contains N: statements you wish to  execute. 
This allows you to see re-defined characters even if the character 
definitions are in a file other than the one in which you are editing.  When 
entering the file name, you must enter the entire name (eg. PART7.PIL). If 
you do not wish to enter another file name, just push ENTER.  

CHARACTER EDITOR

To simplify the task of creating your own special characters EZ contains the 
Character Editor.  

Special characters should not be confused with character "fonts". Special 
characters are limited to the standard 8 by 8 pixel character grid. Character 
fonts are used to display characters of smaller or larger proportions. 
Creation of fonts is documented in the section entitled "Font Editor".  

To enter the character editor hold SHIFT and push F8.  The character editor 
is available only after you have used the F8 key to switch EZ from text to 
graphics mode. With the character editor you can: 

1) See the 128 character patterns which makes up the extended character set.  

2) Look up the key combination needed to enter any particular extended 
character into your program file.  

3) Modify one or more extended character patterns.  

4) Create new extended characters.  

In PILOT you re-define a character grid by specifying 64 dots and slash 
characters on a NEW CHARACTER statement. The character editor lets you see 
the character grid in a normal size and in a blown-up size, so that you can 
see and change each dot individually. When you are done editing a character 
with the character editor, the character editor creates the appropriate NEW 
CHARACTER statement and inserts it into your program text for you.  

Once you enter the character editor, the on-screen help menus provide all the 
information you need in order to use it effectively.  

CHARACTER EDITOR MODES

The character editor has two operating modes: GRID MODE and SELECT MODE. In 
GRID MODE you can edit the dot pattern for a selected character.  In SELECT 
MODE you can pick out which character you wish to work on.  To enter the 
character editor in GRID MODE, push the SHIFT-F8 when the cursor is on an N: 
statement. The character represented on the N: statement is automatically 
selected for editing.  

To enter the character editor in SELECT mode push the 
SHIFT-F8 when the cursor is not on an N: statement.  

In either mode you see the entire 128 characters displayed in the upper right 
part of the screen.  The characters are displayed as they are currently 
defined by the N: statements in the current file and those in any extra file 
you named when you pushed F8 to enter graphics mode.  

To the left you see the currently selected character in a blown-up form and 
in normal size displayed in colors 1, 2 and 3. Also shown is the key 
combination you use after F6 to enter this character into your text file and 
the numeric value of the character, from 128 to 255.  

If you are using extended characters the SELECT MODE is an easy way to look 
up the keys you should press to enter any extended character into your text. 
To do this push SHIFT-F8, position the cursor to the desired character, note 
the F6 key combination shown, then push F10 to go back to text editing mode.  

SELECT MODE

In SELECT MODE you can use the arrow keys to select the desired character. 
Then push F9, to go to GRID MODE, to edit the character or push F10 to return 
to text editing mode.  

In SELECT MODE you can copy one character pattern to another as follows: 
First move to the character to be copied, push F3 to pick up the character, 
then move to the destination character and push F4 to copy it.  Notice that 
to the left of the character table is the character you have currently picked 
up.  

GRID MODE

In GRID MODE you use the arrow keys to move the cursor around within the 
blown-up character cell. You can use the various function keys to modify the 
character pattern as you wish.  Note that the starting grid is saved in the 
"picked up" character spot. If you accidentally destroy the character grid as 
you edit, you can put it back by pushing F4. You can pick up the current grid 
at any time by pushing F3 again.  

Once you have finished with the character, you can push either F9 or F10. In 
either case, the character editor changes or inserts the appropriate N: 
statement in your text file. If you push F9, then you are moved to SELECT 
MODE to select another character for editing. If you push F10 you are 
returned to text edit mode.  

GRID MODE FUNCTION KEYS

Arrows - move cursor 1 space in any direction (if stream mode is on, then set 
or clear the dot) 

F1 - turn dot on and turn off stream modes  

F2 - turn dot off and turn off stream modes  

shift F1 - toggle stream set mode  

shift F2 - toggle stream clear mode 

F3 - pick up grid and save it  

F4 - restore grid to last picked up value  

F5 - invert all dots in the grid  

shift F5 - clear grid (turn all dots off)  

F6 - rotate grid clockwise 90 degrees  

shift F6 - reflect grid across a vertical center  

F7 - roll grid one bit to the left  

F8 - roll grid one bit up  

F9 - save N: statement and goto SELECT mode  

F10 - save N: statement and goto text editor  

HOW TO WRITE A MACRO FOR EZ

The user of EZ can call upon pre-made code sequences which are included in 
the user program by use of the F7 function key. A pre-made code sequence is 
called a MACRO and is stored as a text file. By convention, PILOT language 
macros are named with a file suffix of ".PIM". Usually a macro is used to 
include the code in a program to perform some well-defined task. Such a task 
might be to display a menu, ask a multiple choice question, or update a 
student score record.  

The program author can save much time by using a macro rather than taking the 
time to write a commonly used code sequence over and over. Often the macro 
has been written ahead of time by another party, but the author might create 
personally useful macros also.  

The following code could be stored in a file ANIMATE.PIM and used to move the 
word "Hello" across the screen.  

       TS:G10,10
       TS:*20(A Hello;D3;Wr)

To use it the author would push F7, type the name ANIMATE.PIM, and the above 
two lines would be copied into the current program file.  

SYMBOLIC PARAMETERS IN A MACRO 

Very often the desired code sequence needs to be expanded in slightly 
different ways depending on the exact needs of the program. For this reason a 
macro can be written such that symbolic parameters can be filled in by the 
user each time the macro is expanded. For example, assume that the above 
macro should permit the author to determine what word is moved across the 
screen. The file ANIMATE.PIM could be modified as follows: 

       TS:G10,10
       TS:*20(A ?a;D3;Wr)

Now, when the author calls upon the macro, EZ prompts the author for the 
value to be substituted in where the symbolic parameter "?a" is found. If the 
author replies "happy", then the code that is expanded into the author's text 
is: 

       TS:G10,10
       TS:*20(A happy;D3;Wr)

The same technique could be used for the starting position, number of steps 
to take and delay time: 

       TS:G?a,?b
       TS:*?c(A ?d;D?e;Wr)

Now when the author calls upon the macro, EZ prompts for five symbolic 
parameters: ?a, ?b, ?c, ?d and ?e.  

One macro can use up to 20 different symbolic parameters, named ?a through 
?u. Upper and lower case letters can be used and are considered equal. When 
expanding the macro into the text, EZ prompts for the string to be 
substituted for each symbolic parameter on the first occurrence of the 
parameter. Then the string is substituted for all occurrences of the symbolic 
parameter within the macro.  

?SET COMMAND

A macro can also set the value of a symbolic parameter directly by inclusion 
of a ?SET command line. The ?SET command line is not ever present in the 
resultant expanded text. The function of the ?SET command is only to set the 
value of a symbolic parameter. The format of the ?SET command is as follows: 

       ?SET a=value

"a" represents one of the symbolic parameters,"a" through "u". The value 
string is assigned to the symbolic parameters.  

LABEL SYMBOLIC PARAMETER

There is one special symbolic parameter, signified by four question marks, as 
shown in this example: 

       *A???? T:#N
       C:N=N+1
       J(N<10):A????

EZ substitutes a unique four digit number for the ????. It is unique in that 
prior to expanding the macro, that number is not present anywhere in the 
text. Once the four digit number is selected, it is substituted for each 
occurrence of the ???? in this expansion of the macro. If the same macro is 
expanded again, then a new four-digit number is used. In this way a macro can 
contain labels which are guaranteed to be unique for each occurrence of the 
macro.  

?REM COMMAND

It is possible to insert remarks or instructions to the user within a macro 
using the "?REM" command. For example: 

       TS:G10,10
       ?REM Enter the word to animate.
       TS:*20(A ?a;D2;WR)

In the above case, the user would see the message "Enter the word to 
animate." just prior to the prompt for the symbolic parameter "?a". This 
could be used to inform the user of the macro as to the expected values to be 
filled in. The ?REM line is not included in the macro output.  

CONDITIONAL MACRO EXPANSION

There are several macro commands which can be inserted in a macro to control 
how it is expanded. It is possible to conditionally include or skip sections 
of code via the setting of the "expand flag". When the expand flag is on then 
text lines are included in the result, when the expand flag is off then text 
lines are skipped. The macro commands which can affect the setting of the 
expand flag are shown below. Each command must start at the beginning of a 
line. The keyword may be upper or lower case. The command line itself is not 
placed in the resultant expanded code.  

The conditional macro statements are show below.  

?ON

turn on the expand flag

?OFF

turn off the expand flag

?ELSE

invert the setting of the expand flag

?ASK question text

The question text is presented to the user. If the user responds by pushing 
the "Y" key then the expand flag is turned on. Otherwise it is turned off.  

?IF a=value

"a" represents one of the symbolic parameters, "a" through "u". If the 
symbolic parameter matches the value string, then the expand flag is turned 
on. Otherwise it is turned off.  


