INTRODUCTION
VARIABLE DECLARATION
LOOPS
FILE MANIPULATION
COMPILER QUIRKS
MISCELLANY
: This file was written to try and help you to understand how to
use some of the special features of S-BASIC. I have assumed a
fairly good understanding of BASIC programming on your part. Much of
the material in here was taken verbatim from the programmers
manual supplied with your computer, but I hope I have presented
it in a somewhat easier to use format. 

Part B contains some very explicit instructions on how to declare
variables. I did not go into global versus local variables,
common and based variables or any of the other very advanced
features available with S-BASIC. My intent was to simply clarify
how to get started programming with S-BASIC. 

Part C is a discussion of using loops in S-BASIC. Again this is
just to show the format for using them and not the various ways
in which they can be used

Part D is a discussion of how to access files with S-BASIC. Those
of you who are used to programming in M-BASIC will be very
pleased with the disk I/O available in S-BASIC. It is easy to use
and requires a minimum of program steps.

Part E is a collection of a few very informal observations
regaurding error messages you will run into while compiling your programs

Part D is up to you. See HELP.HLP for instructions on how to
write your own HELP files or alter someone elses.  














:     The most formidable obstacle in writing in S-BASIC is
variable declaration. We've all had to do it at one time or
another(dim statements for example) but it has never been forced
on us as brutally as S-BASIC requires. Almost all high level
languages other than BASIC require a good deal of variable
declaration and S-BASIC provides a fairly gentle introduction
to this difficult concept.
 

     Variable declaration in S-BASIC takes the following form:

FORMAT:

VAR(IABLE) NAME(,NAME...)=TYPE

     There are six types of variables in S-BASIC:

(1)REAL
(2)REAL DOUBLE
(3)INTEGER
(4)FIXED
(5)CHARACTER
(6)STRING

 S-BASIC allows up to 32 letters in a variable name so you can get
quite creative.(you can also screw over anyone trying to read
your programs, so be judicious)
You can declare as many variables as you like in a single line,
and you can DECLARE THE SAME TYPE OF VARIABLE MORE THAN ONCE.

                      TYPE  REAL


EXAMPLE

VAR X,Y,T,V,YOURNAME=REAL

Real variables are binary floating point numbers. there are about
6 digits of accuracy. If when you input a number, say "4.56", it
will be printed with the decimal point floated,ie wherever you
put it. If however, the number is too large, it will be printed
in scientific notation, and look something like this:

                     6.12378E11                

                    TYPE REAL.DOUBLE      
                 
REAL.DOUBLE allows you to have 14 digits of accurracy, hence
there will be greater precision when you do calculations.
If you try to let x = 27895764 and x is a simple real variable,
you will end up with something like 2.7895E7 and afew digits are
lost. Similarly if the stock number for an item in a warehouse is
3048295, you must declare it as a real.double to keep all the
digits. 
                     TYPE INTEGER

     INTEGER variables are most commonly used as counting
variables in loops, such as I,J etc. For example:

                FOR I = 1 TO 10 STEP 2

Integers take up a lot less room in memory and hence execute very
nicely, until you try to make one equal .004(ie NO decimal places allowed)
you declare integers like so:

EXAMPLE

VAR I.J,M = INTEGER

The number must be between +32767 and -32767, otherwise the number
simply wraps around itself. for example if you set an integer
variable to the valu of 32768, the computer will store -1

                   TYPE FIXED:

FIXED variable are mainly for buisness applications. It allows 14
digits of accuracy. The name fixed refers to the fact that the
decimal points will be formatted so as to line up whenever the
number is printed 
                   3.143
                 423.55
                 647.675   

EXAMPLE
                VAR MONEY = FIXED

              
                 TYPE CHARACTER 

    Type CHARacter variables are used in things like yes/no
questions . This allows any single character to be
assigned to the variable, for example:

LET A = "k"

LET ANSWER = "y"

VAR ANSWER,ANSWER1=CHAR

                  TYPE  STRING 

A string variable may contain any printable ascii charactrer
except an ascii null* The variable can be any length up to a maximum
of 255 characters. the format for declaring string variables is
the following:

VAR NAME<,NAME>=STRING:<LENGTH>


Where length refers to the *maximum* length of the string and
can be any integer from 1 to 255
80 is the default value
                      

                         ARRAYS

Arrays must be declared slightly differently than simple variables.
space must be set aside in memory to use an array.UNLIKE OTHER BASICS
THERE IS NO DEFAULT VALUE FOR ARRAYS IN S-BASIC. You MUST DECLARE ALL
ARRAYS WITH A DIM STATEMENT. This can be somewhat annoying for
those of you used to other basics but it is a good practice in
any case.

FORMAT

            DIM TYPE NAME(# of rows,# of columns,etc...)

EXAMPLE

            DIM STRING:30 CRONKITE(5,5),MUDD(6,6)
*note the string length is set to 30

:

                         LOOPS

One of S-BASIC's more powerful features is it's iteration
functions,i.e loops.Most basics have for/next loops, and a few
have while do loops,but very few have repeat until  loops.
S_BASIC has them all and then some. 

The FOR...NEXT loop is common to most basics. 
FORMAT:

FOR (NAME) = (STARTVALUE) TO (STOPVALUE) <STEP (INCREMENTE)>
NEXT (NAME)
*step is optional,default is 1

EXAMPLE:

FOR I = 1 TO 10 STEP 1
PRINT CHR$(I)
NEXT I 

In the above example the value of I is incremented by one (the
default vaule is 1 if you do not specify STEP also the value of
step can be negative and in addition the loop can count down
rather than up. ie 4,3,2,1)each time the loop repeats,
until the maximum value is reached
To stop a loop that keeps repeating use <CTRL-S>

The REPEAT...UNTIL loop is very useful when you want something to
repeat until a statement thet you define becomes true.

FORMAT:
REPEAT BEGIN
program lines
END
UNTIL (statement) is true

EXAMPLE:

REPEAT BEGIN
X=X+1 
END
UNTIL X=10 

The BEGIN...END part of the above statement is a very common
feature of PASCAL, and brings to light one of the reasons S-BASIC
is useful. It is a very logical stepping stone from BASIC
programming to more powerful languages like PASCAL and C

You can leave a REPEAT...UNTIL loop with a GOTO/GOSUB statement
or RETURN into a REPEAT loop from a GOSUB. In addition, a
REPEAT...UNTIL loop will always execute at least once, even if
the condition of the statement is true from the outset.

The WHILE...DO loop is very similar to the REPEAT...UNTIL loop
except that the loop will not neccessarily execute if the
coditions set forth at the outset are true. In other words the
conditions neccessary for the loop to execute are defined before
the loop is executed, and if they are not met the loop is aborted.

FORMAT:
WHILE statement is true
DO BEGIN
program lines
...
...
END

EXAMPLE:

WHILE X<10
DO BEGIN
LET X = X + 1
END
:
                         DISK INPUT AND OUTPUT

File manipulation is very easy with S-BASIC. It allows you to
read from and write to serial and random files in both ASCII and
binary format and it does so with a minimum of program steps.   

There are two types of files you will work with, SERIAL, and RANDOM.
The only difference between the two is that random files
designate a specific amount of memory for the variables that are
entered (regardless of length or size) and serial files use only the
amount of memory that the variable occupies. ,The random file is
therefore divided up into equal SECTORS(see below), each of which
contains the data that you specify. If you number the sectors,which
S-BASIC does, you then have a way of searching for a specific
group of data without having to search the entire file. A sector
then is like a small serial file, and therefore you can consider a random
file to be a collection of small serial files, each of an equal
size, that you can access by calling the number of that file.
The commands for writing to or from random and serial files is
therefore slightly different, ie you must specify the sector when
you are writing to a random file. Most of the work you do will
require you to use random files. The ability to search through
the file and specify which sector to read greatly increases both
the speed and the power of the programs that you will write. 

If this all seems somewhat confusing, perhaps some pictures will help:

serial files store data based upon the amount of room the datum occupies

__________________________________________
|         |                     |         | 
|   a(10) |      a(11)          |   a(12) |
|_________|_____________________|_________|

Whereas random files store each datum in a box of the same size
regaurdless of size.
____________________________________
|           |          |           |    
|    a(10)  |    a(11) |    a(12)  |
|___________|__________|___________|

therefore, you can number the boxes 1,2,3 etc. and read what is
in them just by calling the number. This is much faster than
reading a file into an array to do searches.

                       COMMANDS 

The commands that you will use fall under three catagories, those
that create the channels, those that operate on the system
directory to add delete and rename files and those that actually
allow you to input and read data from the disk.


The command FILES opens up the channels with which you
will read and write to the disk. In this statement, the type of
file(RANDOM, or SERIAL) is specified as is the size of the blocks
or sectors. The number of channels you can use is determined by
the number of times you specify a file up to a maximum of 32. 

FORMAT:

FILES R/S(<size>){,R/S(<size>)...}

EXAMPLE:
FILES R(128),R(128),S(2)

The above example designates three channels, 0,1, and 2.
the first channel(0) is for a random file with the number of bytes
per record set at 128. The second(1) is for another random
channel with a record size of 128 bytes, and the third(channel
number 2) is for a serial file with a sector length of 2.
If you are not familiar with the vocabulary so far see the HELP
file FILES.HLP
You can also use symbolic values for the record sizes and file
numbers in all of these statements. For example,
FILES R(RECORD.SIZE),S(BUFFER.SIZE)...

Well, you can now do input and output with the files but not
until the file exists. The CREATE statement will make an entry
into the directory with the name you specify.
format:
CREATE FILE.NAME

where the file name has the structure of a normal CP/M file such
as b:test.dat.NOTE, you can also create those files with PERFECT
WRITER or ED

EXAMPLE:
CREATE B:GROWTH.DAT,A:SIZE.DAT...

DELETE and RENAME do just that, delete or rename the file specified

EXAMPLE: DELETE B:GROWTH OR RENAME B:GROWTH.DAT TO A:GROWTH.DAT   

A file is opened for input or output with the OPEN statement.
Using the files CREATEd above we would open the file with the following:

OPEN #0;B:GROWTH.DAT

This would open B:GROWTH as a random file with a record length of 128 bytes
per record, on channel #0(remember the files statement previously)

Now, to write something to the disk we would use the following:

write #0,1;body.weight,height

This would write the variables body.weight and height to  the
first record in B:GROWTH.DAT

To read those value is very similar but trhe READ statement is
used instead.

READ #0,1;body.weight,height   

This would read the values for body.weight and height from the
first record in B:GROWTH.DAT

The format for writing to disk files is 

for serial: WRITE #(CHANNEL);<NAME>,<NAME>...
for random: WRITE #(CHANNEL),(RECORD);<NAME>,<NAME>....

The format for reading those files is:

for serial: READ #(CHANNEL);<NAME>,<NAME>...
for random: READ #(CHANNEL),(RECORD);<NAME>,<NAME>...

Once you have completed writing to a file you must close the
channel you were writing on in order to preserve the data in the buffer
The format is:

CLOSE #(CHANNEL)

Where (CHANNEL) is the number of the channel you were writing to.
 So to sum up what we have written, here is the completed program.

VAR BODY.WEIGHT,HEIGHT = REAL
CREATE B:GROWTH.DAT
FILES R(128),R(128),S(2)
INPUT "BODY WEIGHT";BODY.WEIGHT
INPUT "HEIGHT";HEIGHT
OPEN #0;B:GROWTH.DAT
WRITE #0,1;BODY.WEIGHT,HEIGHT
CLOSE #0
OPEN #1;B:GROWTH.DAT
READ #1,1;BODY.WEIGHT,HEIGHT
PRINT "BODY WEIGHT IS";BODY.WEIGHT
PRINT "HEIGHT IS";HEIGHT
END

The first line creates the real variables BODY.WEIGHT, and HEIGHT.
The second line creates an entry in the directory for the file B:GROWTH.DAT.
line 3 opens up 3 channels for writing to the file, two random
and one serial, with record lengths of 128 bytes and 2 sectors respectively.
lines 4 and 5 input the two data. Line 5 opens the file B:GROWTH.DAT
Line 6 writes the data to the file in sector number 1. Line 7
closes the file. The rest I'll leave to you 

:

     The biggest problem you will run into in trying to compile your
programs is not leaving any blank lines at the bottom of the
file. This is mentioned is the S-BASIC manual in a very obscure
chapter, but it is really quite essential to get your programs to
run. The compiler will go into a series of endless loops trying
to find the end of your file.

If that doesn't solve all of your problems check to make sure
that all of the variables that you use are declared! You will get
the error message "UNKNOWN OPERAND" if you don't have them all declared.
From there on you simply have to correct errors from the TOP
DOWN! S-BASIC tends to get confused after about three errors in a
program, so if after correcting a few you don't see any more errors,
ignore the error messages and try to compile your program. If it
doesn't work correct the remaining errors and try again.

:
:GROWTH.DAT
Line 6 writes the data to the file in sector number 1. Line 7
clo