PC/PILOT LANGUAGE REFERENCE MANUAL - Version 3.0

Notice: On your PC/PILOT diskette is a text file named README, with 
additional documentation  you need. Use the DOS command TYPE README to 
display it. 

Washington Computer Services, Bellingham, Washington, U.S.A. 

COPYRIGHT NOTICE

This manual and the PC/PILOT program COPYRIGHT 1985-1994 Larry Kheriaty 

DISCLAIMER NOTICE

No warrantees are made with respect to the adequacy of the software for any 
particular purpose. 

Contents

Chapter 1. Using PILOT
        Learning the PILOT Language . . . 1-1
        How to Install PILOT . . . 1-1
        System Requirements . . . 1-2
        Sample Programs . . . 1-2
        How to Write a Program . . . 1-2
        How to Print a Program . . . 1-3
        How to Run a Program . . . 1-3
        PILOT Program Sizes . . . 1-4

Chapter 2. PILOT Statements
        PILOT Statements . . . 2-1
        Statement Labels . . . 2-2
        Modifiers . . . 2-3
        Conditionals . . . 2-4
        Accept . . . 2-6
        Compute . . . 2-12
        Dimension . . . 2-17
        End . . . 2-20
        File . . . 2-21
        Graphics . . . 2-28
        Jump . . . 2-37
        Keep Records . . . 2-41
        Link . . . 2-42
        Match . . .  .2-43
        New Character . . . 2-48
        New Height . . . 2-50
        New Font . . . 2-51
        New Key . . . 2-55
        Problem . . . 2-56
        Poke, Out . . . 2-59
        Remark . . . 2-60
        Sound . . . 2-61
        Type . . . 2-62
        Type Screen . . . 2-67
        Use . . . 2-77
        Video . . . 2-78
        Wait . . . 2-80
        Execute Indirect . . . 2-81

Chapter 3. Operators and Expressions
        Data Types . . . 3-1
        Variables . . . 3-2
        Subscripting . . . 3-3
        Numeric Constants . . . 3-6
        String Constants . . . 3-7
        Operators . . . 3-8
        Functions . . . 3-9
                                                  
Chapter 4. GOTO and Escape Commands
        GOTO Command . . . 4-1
        Escape Command . . . 4-1

Chapter 5. Error Messages . . . 5-1

Chapter 6. Distributing Programs . . . 6-1
                                                    
Chapter 7. EZ Editor
        EZ Function Keys . . . 7-1
        Using the Pick Stack in EZ . . . 7-3
        Search and Replace . . . 7-4
        Macros in EZ . . . 7-4
        Extended Characters in EZ . . . 7-5
        Character Editor . . . 7-6
        Select Mode . . . 7-8
        Grid Mode . . . 7-8
        How to Write a Macro for EZ . . . 7-10

Chapter 8. Sprites
        Sprites . . . 8-1
        How to Create and Edit Sprite Tables . . . 8-4
        Using Sprites in a PILOT Program . . . 8-11
        Sprite Commands . . . 8-13
        Sprite Examples . . . 8-16

Chapter 9. PILOT Tutorial . . . 9-1

Chapter 10. Font Editor           
        Using the Font Editor . . . 10-2
        Main Menu . . . 10-2
        Select Mode . . . 10-3
        Fat-Bits Mode . . . 10-5
        Changing Global Parameters . . . 10-10

Appendix A: PILOT Language Summary . . . A-1

Appendix B: PILOT Character Set . . . B-1

Appendix C: Student Records . . . C-1



Chapter 1. USING PILOT

This chapter explains how to install and operate PILOT. 

LEARNING THE PILOT LANGUAGE

For the person unfamiliar with programming, a beginner's tutorial is found in 
chapter 10 of this manual. For the person already familiar with programming 
chapter 2 describes the various statements of the language. 

Appendix C lists various other resources that may be helpful in learning and 
using PILOT effectively.  

Regardless of your particular level of expertise, the first step to take is 
to install PILOT according to the instructions found below. 

HOW TO INSTALL PILOT

PILOT requires no special installation. All you need to do is make a working 
copy of the PILOT distribution diskette, then store the original in a safe 
place. You can make a working diskette by following these steps: 

       1. Boot DOS, if not already running 
       2. Place a blank diskette in drive B: 
       3. Enter the command   FORMAT B:
       4. Place the PILOT diskette in drive A:
       5. Enter the command  COPY *.* B: 

If you have a fixed disk you should create a directory  called \PILOT,then 
copy all files from the PILOT diskette to that  directory.  

When working with PILOT place a working copy of the diskette in the current 
default disk drive.  (On a fixed disk, change to the \PILOT directory.) If 
you need more space on your working diskette, you can remove all the sample 
programs by the command ERASE SAMPLE*.PIL .  

SYSTEM REQUIREMENTS 

PILOT works best if you have at least 256K bytes of memory. Although PILOT 
will run on a 128K system, program size and the use of some memory-intensive 
features will be restricted.  

Although PILOT operates on either a monochrome or color video adapter, many 
of PILOT's graphics features are available only on a color video adapter.  

SAMPLE PROGRAMS

Several sample programs are provided on your PILOT diskette.  Each one has a 
file name of the form SAMPLEn.PIL. n represents a number.  

You can run a sample program by entering: 

       PI  SAMPLEn
  
Some of the samples are very simple. Others demonstrate fairly advanced 
programming techniques.  Run each program and observe the results. Then 
examine the program file to see how the program was written and to obtain 
examples of various types of statement sequences.  

Particularly useful is SAMPLE1.PIL.  It allows you to enter PILOT statements 
one at a time. Each statement is executed immediately as it is entered.  This 
can help you to try out various PILOT features quickly without writing a 
program.  


HOW TO WRITE A PROGRAM

A PILOT program is a text file which contains a series of PILOT STATEMENTS. 
Programs are written using a text editor to create the text file and stored 
on disk under a name of your choosing.  

Included with PILOT is the EZ editor. It is designed to be simple to use 
while providing several special features to aid in PILOT programming. The EZ 
editor is described in a later section of this document.  Since PILOT 
programs are text files, you can use any other text editors or word 
processors that operate on DOS text files.  

When you write a PILOT program, you must give it a name of the form name.PIL, 
where name is any word you choose. .PIL is called the file type and 
identifies the file as a PILOT program.  


HOW TO PRINT A PROGRAM  

To list the names of all PILOT programs in the current disk and directory use 
the DOS command: 

       DIR  *.PIL 

To list a program on the screen use the DOS command: 

       TYPE  name.PIL 

To print the listing on your printer, first ready the printer, then enter the 
command: 

       COPY  name.PIL  PRN: 


HOW TO RUN A PROGRAM 

To begin execution of a PILOT program enter: 

       PI  name 

where name.PIL is the path name of the file which contains the PILOT program 
to be run. The suffix of ".PIL" is appended automatically by PILOT. You 
should not type it when entering the file name.  

Per normal DOS conventions, you can precede the PI by an optional drive 
designation if the file PI.EXE is not in the current disk drive.  

The file name can be a full DOS path name if the file is not in the current 
disk or directory.  Thus the program to be run can be in any directory, any 
drive, and any network node desired.  

When a program ends, control is returned to DOS.  

A program may be prematurely canceled at any time by pushing ctrl C (ie, push 
the C while holding down the ctrl key).  

PILOT PROGRAM SIZES

When PILOT starts, a program buffer is set aside from the available memory. 
Unless the PI command line indicates otherwise, the buffer size is 32K bytes.  
You can specify another program buffer size by adding a parameter to the PI 
command line as follows: 

      PI  name  n

where "n" can be a number from 1 through 8. The program buffer size is set to 
n*8K bytes. A maximum value of 8 indicates a program buffer size of 64K 
bytes.  If the requested amount of memory is unavailable, then a program 
buffer of 8K bytes is allocated from PILOT's internal string space.  

Chapter 2. PILOT STATEMENTS

A statement follows the following general format: 

*label  op-code <modifiers/conditionals> :   arguments 

The *label is optional.  The modifiers may be coded in any order.  If a 
particular modifier does not make sense for the op-code, the modifier is 
ignored.  The op-code represents the type of statement to be executed.  The 
op-code, modifiers and conditionals may be upper or lower case.  There may be 
no spaces within the op-code, modifiers or conditionals (except within 
conditional expressions).  There must be a colon after the op-code modifiers 
and conditionals.  After the colon there may be further arguments.  The 
format and meaning of the arguments after the colon depend on the particular 
op-code.  

A PILOT program is a sequence of statements.  Each statement is written on 
one line. The maximum statement length is 256 characters. A program may 
consist of any number of statements, limited only by the amount of disk space 
available. Programs may be created using any editor which produces standard 
ascii formatted text files. It is recommended that you use the EZ editor 
provided with PILOT to create your program files.  

EXAMPLE 1: A simple Type statement.

       T:Welcome to Biology 301.

See also:   STATEMENT LABELS, MODIFIERS, CONDITIONALS

STATEMENT LABELS

A statement label is preceded by a "*" character and consists of one to six 
alphanumeric characters (letters and digits). A label may be alone on a line 
or may precede a statement on the same line.  Upper and lower case letters 
are considered equivalent within labels.  

A label serves the purpose of providing a branch point (place to jump to). 
Unless instructed otherwise, PILOT runs a program by executing successive 
statements in the order that they occur in the program. Using the Jump (J) 
statement provides a means of altering the natural program flow by jumping 
from one location within the program to another location, marked by a label.  

For efficiency, PILOT automatically optimizes label addressing for labels 
that are at least two characters long. For this reason, it is recommended 
that one-characters labels not be used when execution speed is important.  

EXAMPLE 1: Label as a target for a Jump; label written on same line as 
statement.  

       T:We will now proceed directly to part3.
       J:PART3
       . . .
       . . .
       *PART3   T: The next question is...


EXAMPLE 2: Label written alone on a line. 

       *REVIEW
       T:Let us look again at the diagram...
      

See also:  JUMP

MODIFIERS

A modifier is a letter appended to an op-code.  It causes change in the way 
the statement is executed. The letters used as modifiers are H, J, S and X. 
The specific meaning that a modifier takes on depends entirely on the op-code 
to which it is appended. The modifier letters are used to designate 
variations on the operation of the basic statement types. 

For example, the "S" modifier, when appended to the M: op code gives the 
"match-spelling" statement. In this case the "S" modifier is sometimes 
referred to as the "spelling" modifier.  

The same letter, S, when appended to the A: op code yields the "accept 
single" statement. It modifies the normal operation of the accept statement 
to input an answer of only one key rather than the normal one line. 

If a modifier (H, J, S or X) is appended to any op-code for 
which the meaning is not yet defined, the modifier has no effect on the 
statement. 

CONDITIONALS 

A conditional is a letter, digit or expression appended to any op-code.  The 
conditional causes the statement to be executed only if the condition is 
true.  If it is false, then the statement is skipped.  Each conditional is 
shown below as appended to a TYPE statement, however, each can be appended to 
any type of statement.  

TY: - type if last match was YES

TN: - type if last match was NO

TE: - type if error flag is true

T(exp): - type if expression is true

The expression is evaluated, if it  is true (non zero) then the statement  is 
executed, otherwise it is skipped.  

TC: - type if previous expression was true

Tn: - type if accept counter=n

n may be a number from l to 9. Type if n is equal to the accept counter. The 
accept counter is a value which tells how many times the last accept has been 
executed in a row.  


Any number of conditionals may be appended to the op-code.  All must be true 
for the statement to be executed. If any conditional is found to be false, 
the remainder of the statement is skipped over, and execution continues with 
the next statement in line.  

EXAMPLE 1: Y and N conditions to test a student response for correct or 
incorrect.  

       T:How many feet in a yard?
       A:
       M:three
       TY:Correct
       TN:Incorrect

EXAMPLE 2: Conditional expression and C condition to re-test same condition.  
    
       T(TRY < LIMIT): No, look at this.
       JC: REVIEW


EXAMPLE 3: Conditional expression used to create a loop to print digits 1 
through 9.  

       C: I=1
       *LOOP  TH:#I,
       C:I=I+1
       J(I<10):LOOP


EXAMPLE 4: N and digit condition used in combination to give successive 
hints.  

       T:What do we call an 8 sided figure?
       A:
       M:octagon
       TY:Right
       TN1:Hint: A STOP sign is one.
       TN2:Hint: An octopus has eight arms.
       TN3:That's your third wrong try.

EXAMPLE  5:  E condition used as a check  for  a numeric answer.  

       T:What is 4+5?
       A: #N
       TE:Please type a number.
       JE:@A
       M:9
       TY:Right.


See also:  MATCH, ACCEPT 
 
ACCEPT - input student response

       A:
       A: $variable$ #variable
       AH:
       AJ:
       AS:
       AX:


ACCEPT is used to input a student response.    When the ACCEPT is 
encountered, PILOT waits for the student to enter an answer. The student 
types a response followed by the Enter key.  While typing the response, the 
student can use the Backspace key to correct typing errors. The response is 
automatically edited  per the space and case options last set on a PROBLEM 
statement.  These options can be used to convert answers to all upper or all 
lower case, or to remove spaces from the answer. The edited response is then 
placed in the system variable %B, also called the answer buffer.  

Characters typed by the student are displayed on the screen.  When the 
student pushes the Enter key to end the response, the cursor is moved to the 
start of the next line. However, if the H (hang) modifier is added to the 
ACCEPT statement then the cursor is left hanging at the end of the student 
response.  


ANSWER LENGTH LIMIT

Unless otherwise specified, the student answer is limited to a maximum of 80 
characters. The An option of the PROBLEM statement can be used to set the 
answer length limit to any value from 1 to 256 characters. The answer length 
limit can not be set to a value greater than 256 characters.  


ACCEPT SINGLE

The S (single) modifier appended to the ACCEPT (AS:) limits the response to 
one keystroke regardless of the current response length limit.  When the S 
modifier is appended to the ACCEPT, no editing of the value is done; it is 
placed in the answer buffer as a one character string.  


USE OF KEYBOARD TYPE-AHEAD

Unless the program indicates otherwise, the student can not type the answer 
prior to the program reaching the ACCEPT statement. The J modifier (AJ:) 
allows type-ahead to be used for this ACCEPT. With type-ahead enabled, keys 
pushed prior to the ACCEPT statement "count" as part of the reply.  


INPUT OF SPECIAL CHARACTERS

Input characters in the range of ascii 32 to 255 are accepted as input data. 
The normal Ascii character set consists of characters from 32 to 127. The 
characters in the range 128 to 255 are used for the text mode extended 
character set, and for user-defined characters. Appendix A contains a 
complete list of the standard codes generated by each keyboard combination.  

The NX: statement can be used to change the code generated by any particular 
keyboard key or combination. If the X modifier is not appended to the ACCEPT 
op-code, then the values input for each key on the keyboard are affected by 
previous NX: statements.  If the X modifier is appended to the ACCEPT (AX:), 
then all keys generate their default standard values regardless of any 
previous NX: statements.  


STUDENT RESPONSE TIMING

Unless otherwise specified, the student can take any duration of time to 
respond. However, a time limit can be set by the Tn option of the P: 
statement. If the student has not pushed the Enter key within the time limit, 
then PILOT proceeds as if the Enter key had been pushed.  

Whether there is a time limit or not, the built-in function TIM(0) returns 
the length of time (in seconds and fractions of a second) taken by the 
student to respond to the last ACCEPT.  


SETTING VARIABLES

One or more string or numeric variables may be placed after the colon on an 
ACCEPT.  Each variable name must be preceded by a $ or a #.  For each string 
variable, the value of the answer buffer is assigned to the string.  For each 
numeric variable, the first number found in the answer buffer is assigned to 
the variable.  If more than one numeric variable is written, each variable is 
set to the same value.  

If a numeric variable is included on the ACCEPT statement, and no number is 
found in the student answer, the E condition is set to true. By checking the 
E condition after the ACCEPT statement, it is possible to determine whether a 
numeric reply was given.  


THE GOTO COMMAND

If the G option has been enabled on a previous PROBLEM statement, the student 
can enter a GOTO command rather than an answer. To do so, the student must 
type: 

       GOTO label 

The label typed by the student must correspond to a label within the program. 
Naturally, this is of use to the student only if the student has been 
instructed as to the possible labels to go to.  Usually, the GOTO command is 
most useful to the program author when debugging or testing the program.  It 
would allow the author to test various sections of the program, skipping over 
other sections not of interest.  


ESCAPE FEATURES

Often it is desirable to allow the student to push certain function keys or 
escape keys to cause pre-defined actions to take place. These actions might 
be a return to a menu, review of a previous question, a help screen, a 
glossary, etc. In many cases you wish the student to be able to use these 
special keys at any time that the student is expected to reply. It would be 
inconvenient to place the necessary statements to do the special key checking 
at every answer point. So PILOT provides for automatic checking of special 
"hot" keys.  

There are two possible levels of key checking available. The E option on the 
PROBLEM statement indicates that the ESCAPE key and the @ key are to be 
trapped. The F option on the PROBLEM statement indicates that the function 
keys, the shifted function keys, and the cursor keypad keys are all to be 
trapped. The program can enable either, both or neither of these options.  
All special keys (except the @ key) are trapped immediately when pressed by a 
student responding to an ACCEPT statement. The @ key is only trapped when 
entered as the first character of a response, and only after the ENTER key 
has been pushed. (The use of the @ key is retained only for compatibility 
with older versions of PILOT.) 

When one of the special keys is detected by the ACCEPT statement, the 
following actions take place.  

       1. The key value is placed in the answer 
       buffer, %B, after any previously typed
       characters.

       2. The ACCEPT statement is immediately halted.

       3. PILOT performs the equivalent to the line
       U:SYSX
       That is, it calls the subroutine named
       *SYSX in the current program.

It is up to the programmer to insure that there is a label *SYSX in the 
program.  The *SYSX routine can determine exactly which special key was 
pressed by: 

       C: F = ASC(%B(LEN(%B))

which would set the variable F to the value 27 for the Escape key, or a value 
from 187 to 221 for one of the function or cursor keys. Appendix A contains a 
complete listing of the codes generated by the various keys. Note that if you 
wish to change the set of keys that are trapped, you can use the NX: 
statement to change the codes received by the various keys. When the effects 
of NX: statements are taken into account, any keys in the range 187 to 221 
are trapped; any other keys are not.  

Once control is passed to the SYSX subroutine, it is up to the program to 
implement whatever action is to take place. At the end of the SYSX 
subroutine, the program could return to re-execute the ACCEPT via: 

       E:@A

The subroutine can also branch off to another location in the program by a 
statement such as: 

       E:MENU3

ACCEPT EXAMPLES

EXAMPLE 1: simple answer input

       T:What is the capital of Norway?
       A:

EXAMPLE 2: accept numeric answer

       A: #X
       TE: I need a number.  Try again.
       JE: @A           

EXAMPLE 3: accept a fill-in-the blank answer
  
       TS:G0,10
       TH:Mary had a        lamb.
       TS:G11,10
       P:A7     
       AH:

EXAMPLE 4: input any one key

       AS:
       T: The key value is #(ASC(%B))
  
EXAMPLE 5: input a timed response

       P:T5
       TH: 6 x 8 = 
       A:
       T:You took #(TIM(0))  seconds.

See also:  PROBLEM, NX:, GOTO AND ESCAPE


COMPUTE - assignment statement

       C: target = expression
       C: target = expression ; target = expression ;
       C: target = expression  \ remarks
 
The COMPUTE statement is used to perform numerical computations, or to 
perform string manipulation. Any number of assignments may be made on one 
compute line by separating each from the previous by a semi-colon. A remark 
or comment may be placed after the assignments by preceding the remark with a 
back-slash, "\".  

Numerical computations consist of operations such as addition, subtraction, 
multiplication, and division.  

String manipulation consists of operations on character strings, such as 
capitalization, picking a word out of a sentence, or combining several words 
into a sentence.  

A COMPUTE statement always contains an = sign.  On the right of the equal 
sign is an expression.  A complete discussion of expressions may be found in 
a later section of this manual.  However, in general, an expression is a 
series of numeric or string operations to be performed which result in a 
value.  The resultant value can be a number, or it can be a character string.  

On the left side of the = sign is a target variable.  The target may be a 
numeric variable, a subscripted array variable, a string variable, a 
subscripted string variable, or the system variables %B or %A.  

The COMPUTE statement evaluates the expression, then assigns, or sets, the 
target to the resultant value.  

ASSIGNMENT TO NUMERIC VARIABLE

A variable that has not been explicitly made to be a string or array is 
called a numeric variable or a simple variable. Such a variable stores a 
single numeric value. If the target of the COMPUTE is a numeric variable, 
then the expression is expected to yield a number when evaluated. The number 
value is stored in the variable, replacing any previous value the variable 
had. If the expression happens to produce a string value rather than a 
numeric value, PILOT automatically converts the string value into a numeric 
value, then assigns the numeric value to the the variable. To convert the 
string value to a numeric value, PILOT takes the first number found in the 
string, searching from the left. If there is no number in the string, the 
numeric value is zero.  

The system variable %A, which contains a count of the number of times the 
current ACCEPT statement has been responded to, is considered to be a numeric 
variable.  It can be used in an expression or can be the target of the 
COMPUTE.  

EXAMPLE 1: assignment to numeric variable

       C: X = 5 + 4                         sets X to 9
       C: X = X / 2                         sets X to 4.5
       C:AGE="I am 14 years old"            sets AGE to 14
       C: X=1 ; Y=2 ; Z=3                   sets 3 variables

ASSIGNMENT TO SUBSCRIPTED VARIABLE

An array variable is a variable name which represents a list of numeric 
values. The DIMENSION statement is used to create an array variable. An 
individual item within an array can be identified by placing the number of 
the item in parentheses after the array variable name.  The number in the 
parentheses is called a subscript. Array items are numbered from 0, for the 
first item in an array, to the number specified in the Dimension statement 
which created the array.  Each item in an array can be thought of as a 
numeric variable.  The only difference is that a variable is identified by 
its own unique name, whereas an array item is identified by both an array 
name and a subscript. Assignment to an item within an array is similar to 
assignment to a numeric variable.  

EXAMPLE 2: assignment to the items in an array

       D:Z(3)        
       C:Z(0) = 100  
       C:Z(1) = 200  
       C:Z(2) = 300  
       C:Z(3) = 1000 

ASSIGNMENT TO A STRING VARIABLE

A string variable is a variable which can store a character string. A 
character string is a list of characters, such as "ABC", "Banana", or "The 
Declaration of Independence". A string variable name always ends with a "$". 
Also, before a string variable can store a string value, the DIMENSION 
statement must be used to set aside space for the string variable. When a 
string variable is created by the DIMENSION statement you must specify the 
number of characters, or bytes, to be set aside for the string variable.  
This number is called the maximum length of the string variable. At any time, 
the string variable may store any number of characters from 0 to its maximum 
length. The number of characters stored in a string at any particular time is 
called the current length. A string which contains no characters at all is 
called a null string. A null string has a length of zero.  

The system variable %B, which always contains the response given by the 
student at the last ACCEPT statement, is a string variable with a maximum 
length of 80 characters. It can be used in an expression or as the target of 
a COMPUTE.  

When the target is a string variable the expression is expected to yield a 
string value.  If it happens to yield a numeric value, then PILOT 
automatically converts the numeric value to a string value by creating a 
string which represents what the numeric value would look like if printed out 
on the screen.  It may seem odd to distinguish between a string value of 
"123.45" and a numeric value of 123.45; it is only within computers that such 
distinctions matter at all. PILOT frees you from being concerned with this 
distinction by automatically converting to the form needed to fit the 
context.  

The expression value is assigned to the string variable, replacing any 
previous value the string variable may have had.  If the expression value is 
longer than the maximum length of the string variable, then the value is 
truncated (cut off on the right end) to the maximum length of the string 
variable.  After the assignment, the current length of the string variable 
will be the number of characters actually assigned to the string variable.  

EXAMPLE 3: assignment to string variables

       D: DAY$(10)
       C: DAY$ = "TUESDAY"
       C: DAY$ = "Sun Oct 6, 1950"
 
The last statement above results in variable DAY$ set to "Sun Oct 6," since 
its maximum length is 10.  

ASSIGNMENT TO A SUBSCRIPTED STRING

A string variable can be thought of as storing a list of characters or bytes. 
It is possible to refer to a piece of a string, sometimes called a substring. 
To do so, place subscripts after the string variable name within parentheses. 
You can refer to one character within a string by placing one subscript after 
the string variable.  The characters within a string are numbered from 1 (for 
the first character) to the current length of the string. To refer to several 
characters within a string, you place two subscripts in parentheses, 
separated by a comma.  The first subscript denotes the starting position 
within the string, the second denotes the number of characters in the 
substring. If the second subscript is omitted, the length of the substring
is 1.  

There are a few rules about what happens if you specify a target substring 
with a starting position and length which are out of the bounds of the 
current string length: 

(1) Since the first position of a string is position 1, if you specify a 
position less than 1, then  PILOT assumes you mean position 1.  

(2) If you give a position greater than the current length of the string 
variable, then PILOT expands the string variable as necessary by adding 
blanks to the end of it.  

(3) If you give a position greater than the maximum length of the string, 
PILOT assumes you mean to position at the last character of the string.  

(4) If you specify a length which would go over the end of the string, the 
substring goes only to the end of the string.  

The result of an assignment to a substring is determined by several factors: 
the length of the expression value to be assigned, the current and maximum 
length of the string variable, and the values of the subscripts after the 
string variable name.  

To assign a value to a subscripted string variable the expression value is 
computed, if it is a number it will be converted to a string.  Then, if the 
string value is longer than the substring to which it is being assigned, it 
is truncated (cut off from the right end) to the appropriate length. If the 
expression value is shorter than the substring to which it is being assigned, 
the value is padded on the right end to the appropriate length by appending 
spaces.  

EXAMPLE 4: assignment to substrings

       D: X$(10)
                                       (creates string X$)
       C: X$(10) = " "
                                       (sets X$ to 10 spaces)
       C: X$ = "ABCDEFGHIJ"
                                       (X$ now "ABCDEFGHIJ")
       C: X$(4) = "d"
                                       (X$ now "ABCdEFGHIJ")
       C: X$(3,5) = "xzy"
                                       (X$ now "ABxyz  HIJ")
       C: X$(9,5) = "QRSTUV"
                                       (X$ now "ABxyz  HQR")

DIMENSION - allocate arrays and strings


       D: variable (size), . . .
       DX: variable (size), . . .

DIMENSION creates an array of numbers or a character string.  If the variable 
name ends with the "$" character a string is created, otherwise an array is 
created.  Any number of arrays or strings can be created in one DIMENSION 
statement by separating each variable and size from the next by a comma.  

If an array or string has been created previously in the program, then an 
attempt to dimension the same variable again will first cause the previous 
contents of the array or string to be discarded. Then the new array or string 
is created as if for the first time.  You should normally place all the 
DIMENSION statements for a program toward the beginning of the program, in 
such a place that they will be executed only once.  

DIMENSION OF A NUMERIC ARRAY

An array is a list of numeric values. Each value can be accessed by the array 
name, followed by a subscript. A subscript is a numeric value in parentheses. 
The DIMENSION statement sets aside enough space to hold the specified size, 
plus one.  

The first item in an array is accessed by a subscript of 0, the next by a 
subscript of 1, and so on. The last item in an array is accessed by a 
subscript equal to the size value given on the DIMENSION statement. When an 
array is created via the DIMENSION statement, we sometimes say that the 
variable has been "dimensioned" to a particular size. When an array is 
created, the various numeric values in the array are not automatically 
initialized to any particular value. The initial value of any particular 
array item might be any number.  

DIMENSION OF A STRING VARIABLE 

If the variable name ends with a "$", then a string variable is created. A 
string variable stores a character string or a list of characters. The size 
given in the DIMENSION statement indicates the amount of memory set aside for 
the string variable and the maximum length character string that can be 
stored in the string variable. At any time the string variable can store any 
string up to the maximum string length.  The number of characters stored in a 
string at any particular moment is called the current length of the string.  

An individual character position in a string variable can be accessed by a 
subscript. The first position of a string has subscript 1. When a string 
variable is created, it is initially set to a null string (i.e. a string with 
no characters in it). If you then wish to fill the string to its maximum 
length use a COMPUTE statement to assign a blank to the last character 
position. For example: 

       D: XYZ$(3500)
       C: XYZ$(3500) = " "

SPECIAL USES OF STRING VARIABLES

There are several special purposes for string variables. One is to store a 
machine language subroutine to be called via the V: statement. If a string is 
to be used for this purpose, then you must append the X modifier to the D: op 
code when creating the string. This forces 16-byte memory alignment of the 
string start. This factor is only important for machine language programming 
due to the nature of the processor chip, and segment register limitations.  

The second special purpose for a character string is to hold a sprite table. 
A string to be used for this purpose must be created with a size of at least 
2218 characters. A complete explanation of this feature is contained in the 
sprite section of this manual.  

ARRAY AND STRING SPACE CAPACITY

PILOT sets aside approximately 35,000 bytes of space for storage of arrays 
and strings. The amount may be less if the computer memory is less than 256K 
bytes.  Each array takes up 4 bytes per array item. Each string takes up one 
byte per string position. The same pool of space is used for scratch pad 
during various string manipulation operations, so if you get space error 
messages on a statement other than a dimension, you need to leave more space 
for scratch purposes.  

EXAMPLE 1: Create a numeric array with items numbered from 0 to 100.  

       D: LIST(100)

EXAMPLE 2: Create a string to store the student's name.  

       D:NAME$(30)
       T:What is your name?
       A:$NAME$

EXAMPLE 3: Create a string to hold a machine language subroutine, and read 
the subroutine from disk into the string. 

       DX: VEZ$(6000)
       FX:VEZ.BIN
       FI:0,VEZ$

EXAMPLE 4: Create a string to hold a sprite table, and read the sprite table 
from disk into the string. 

       D:SPRI$(2218)
       FX:PLANETS.SPR
       FI:0,SPRI$

EXAMPLE 5: Create two string variables and three arrays in one statement.  

       D: X$(20), Z$(340), A(100), B(200), C(3)

See also:  SUBSCRIPTING

END - terminate subroutine or program

       E:
       E: destination

The END statement has two purposes. First, if the use stack is empty, meaning 
that there is no un-ended USE in effect, then the END statement terminates 
the program and returns to DOS.  

Second, if the use stack is not empty, meaning that there is an un-ended USE 
statement in effect, the END statement pops the top entry off the use stack. 
This entry indicates the return point for the associated USE statement. The 
return point is the statement following the USE statement. If the END 
statement does not have a destination operand after the colon, then END jumps 
to the return point. If the END statement does have a destination after the 
colon then (after popping the entry off the use stack) END jumps to the label 
indicated on the END statement. This feature allows a subroutine called via 
the USE statement to return to either the statement after the USE or to 
another point in the program. This is particularly useful in conjunction with 
the ESCAPE command. The SYSX subroutine might be called from many places but 
might always exit to a menu or other common return point.  

See also:  USE, GOTO AND ESCAPE

EXAMPLE 1: END which always returns to DOS

       *QUIT  E:QUIT

EXAMPLE 2: END used to return from a subroutine

       *SUB T:Metric Conversion Table
       . . .
       E:

FILE - access external or heap file

       FX: filename
       FX:
       FI: position-expression,variable$
       FO: position-expression,value-expression

       FXH: heapsize
       FIH: position-expression,variable$
       FOH: position-expression,value-expression

The FILE statement provides access to disk files, the printer or auxiliary 
(RS-232 serial) port, a network or an in-memory file called the heap. To 
access a file, the program must first open the file. To open a file use the 
FX: statement. PILOT allows one open file at a time.  Whenever you open a 
file, PILOT will close any previously opened file. The FX: statement without 
a filename after the colon, closes an open file without opening another file.  

Once a file is opened, the FI:, FILE IN statement, is used to read data from 
the file into a string variable. The FO:, FILE OUT statement, is used to 
write data from the program to the file.  

