pre-release 0.2 Edited By Dr Phibes
STOS Manual 10: OTHER COMMANDS
Control Structures
GOTO [line number][expression]
expression can be any allowable STOS basic expression involving variables
or constants.
GOSUB [line][expression]
As for GOTO except the program returns to the command after GOSUB when
execution of the GOSUB is completed.
RETURN
The statement used to return from a GOSUB.
POP
This removes the RETURN address generated by a GOSUB and allows you to
leave a subroutine without having to execute the final RETURN statement.
FOR...NEXT
For/Next loops are terminated when the loop counter exceeds the loop control
variable. Up to ten For/Next loops can be nested but it must be remembered
that each FOR requires its own NEXT statement, a line like
NEXT a,b,c
for example is not acceptable.
WHILE...WEND eg.
WHILE condition
list of statements
WEND
The test is made at the start of the loop and the condition must be true
here or the list of statements will not be executed.
REPEAT...UNTIL
As for WHILE WEND except that the test is made at the end of the loop thus
ensuring that the list of instructions will be executed at least once.eg
REPEAT
list of statements
UNTIL a=0
STOP
Halts execution of a program and returns control to the editor. Note that
unlike the END command a program halted in this way can be restarted with
the CONT command,assuming the program has not been altered between stop
and cont.
END
As for STOP except the program cannot be restarted with CONT.
IF...THEN [ELSE]
The command is restricted to a single line.
ON...GOTO
Jump to a line depending on a variable. The variable must always be an
integer.
ON...GOSUB
Jump to a subroutine: as for ON GOTO.
ON ERROR GOTO line
Trap an error within a STOS basic program.line refers to the location of
the new error correction routine. It can take the normal form of a line
number or an expression. It should be remembered that the expression will
only be evaluated once and cannot therefore be used to refer to more than
one routine.
ON ERROR GOTO OFF
cancels the above statement.
RESUME
This instruction is used from within an error trap created by On Error
Goto. The action of RESUME is to jump back to the part of the program which
caused the problem, after the error has been corrected by your routine.
You should NEVER attempt to use GOTO in this context.RESUME has three possible
formats:
resume
Jump back to the statement which caused the error and try again.
resume NEXT
Jump to the statement following the one which generated the error
resume LINE
Jump to LINE number.
ERRN
Contains the number of the last error.
ERRL
Contains the location ( line number ) of the last error.
ERROR
Quits the current program and returns to the editor. A useful way of using
this function is as follows.
ERROR ERRN
returns to the editor and prints the error condition.
BREAK ON/OFF
enables or disables the [control+c] key combination.
The Keyboard
KEY(x)=a$
Function to assign a string a$ to a function key x. a$ is the string that
will be returned whenever function key x is pressed. Note [ ' ] denotes
a carriage return.
k$=INKEY$
Where k$ is the string variable that will be used to hold the key which
has been pressed. If a key is pressed k$ will contain the Ascii code of
the key, otherwise k$ will be set to an empty string "". Cursor keys and
function keys require the use of the SCANCODE function. Not echoed to the
screen.
SCANCODE If INKEY$
detects that a key has been pressed which does not return an Ascii code
it returns a character 0, in this instance the value of the key pressed
will be returned with the function SCANCODE.
CLEAR KEY
Clears the keyboard buffer of all keypresses.
INPUT$(n)
Function to read n characters from the keyboard without echo. FKEY Reads
the function keys directly and returns a value of 1-10 [f-key], 11-20 [shift+fkey].
Quicker than inkey$+scancode.
WAIT KEY
Pauses a program until any key is pressed.
KEYSPEED
repeatspeed,delay Repeatspeed is the delay in 50ths of a second between
each repeated character. Delay is the time in 50ths of a second between
pressing a key, and the start of the repeat sequence.
PUT KEY
Puts a string into the keyboard buffer. [RETURN] can be included in this
string using the [ ' ] character.
Input/Output
INPUT ["prompt";]variable list
If the optional prompt is excluded then the prompt will be a " ? " character.
The variable list can be any list of variable types, each separated by
a comma. For multiple inputs, a comma should be used to separate the inputs,
a carriage return indicates termination.
LINE INPUT
As for INPUT except that the multiple list of variables are separated by
pressing [return] instead of inserting a comma.
PRINT or ?
The ? character can be used at any time to replace the PRINT statement,
although it will be expanded to PRINT in program listings.
USING
Takes a special format string. Any normal alphanumeric characters in this
format string will be simply printed out, but if you include one of the
characters ~ # + - . ; ^ then one of several useful formatting operations
will be performed.~ Any occurrences of the ~ are replaced by a character
from the following string eg. print using "this is a ~~~~~ demonstration";"small"
The string small will be used to fill in the ~ characters.# Specifies the
number of digits to be printed out from a numeric variable. If this number
is greater than the size of the variable then excess # characters will
be replaced by spaces.+ Adds a plus sign to a positive number and a minus
sign to a negative number - includes a sign if number is negative. positive
numbers preceded by a space . Places a decimal point in a number, and centres
it.; Centres a number but doesn't output a decimal point.^ Outputs a number
in exponential form.
DISC ACCESS Sequential Files
A sequential file must be appended with .seq and must be loaded in its
entirety to be used or modified. To access a sequential file the following
three steps must be performed in this order:1 Open the file using OPEN
IN or OPEN OUT2 Access the file with INPUT # or PRINT #
3 Close the file with CLOSE. Note that if you forget to do this, any
changes to the file will be lost.
DISC ACCESS Random Files
Unlike sequential files a random file can be used and altered one entry
at a time. Unlike sequential files which can be of any length, a random
access file has to have each field length defined before records can be
created: field #1,15 as SURNAME$,15 as NAME$,10 as CODE$,10 as TEL$ would
set up a record with four fields, two of which can have a maximum of 15
characters and two of which can have a maximum of 10 characters. To assign
a record to a field use the following format: SURNAME$="Smith"The records
can be written to disc using the PUT command:PUT #1,10 Loads data into
record 10 of the file opened on channel 1.Similarly you can read a record
using the GET instruction.
File Handling Commands
OPEN IN #channel,file$
Opens a file for reading only.channel denotes a number from 1 to 10 to
specify which is used by the instructions INPUT#,LINE INPUT# and INPUT$(#channel,count)
to specify which file is to be read.
OPEN OUT #channel,file$[,attribute]
Is used to open a sequential file for writing using PRINT #. If this file
already exist on the disc it will be erased. Channel is a number between
1 and 10 by which the file will be referred to in all subsequent operations.
File$ can be any string holding the name of the new file to be opened.
The optional attribute allows you to specify the type of file to be used.
See DIR FIRST$ for more details.
OPEN #
Open a channel to a random file or device. There are four forms of this
command;OPEN #channel,"R",file$ (opens a random access file)OPEN #channel,"MIDI"
(opens a channel to the MIDI interface)OPEN #channel,"AUX" (opens a channel
to the RS232 port)OPEN #channel,"PRT" ( opens a channel to the parallel
printer port )
CLOSE #
This function closes the file associated with a channel.
PRINT #
Print a list of variables to a file or device specified by channel.
INPUT #
Reads information from a sequential file or device, if the data to be read
is longer than 500 bytes then the INPUT$ function should be used instead.
LINE INPUT #
Input a list of variables not separated by a comma. There are two possible
variations of this command:
LINE INPUT #channel,variable list or LINE INPUT #channel,seperator$,variable
list
This function is identical to input #. but it allows you to use another
character instead of a comma to separate the individual items of data on
the disc. If no separator$ character is included, then [return] is assumed.
INPUT$(#channel,count)
This reads count characters from the device or file connected to the channel.
EOF (#channel)
If the end of a file has been reached at the current read position then
this function returns a result of true, otherwise false.
LOF (#channel)
Returns the length of an open file
POF (#channel)
Changes the current reading or writing position of an open file eg.
POF(#1)=1000
sets the file pointer to 1000 characters past the start.
FIELD #channel,length1 AS field1$,length2 AS field2$......
Field allows you to define a record which will be used for a random access
file created using the OPEN #channel,"R" command. This record can consist
of up to 16 alphanumeric fields and be up to 65535 bytes in length.
PUT #channel,R
Moves a record from the ST's memory into record number R of a random access
file. Before use, the contents of the new record should first be placed
in the field strings defined by FIELD. Although you can write existing
records in any order you like, you are not allowed to scatter records on
the disc totally at random. This means that if you have just created a
file, you can't type in something like: put #1,1:put #1,5: In this case
there are no records in the file with numbers between 1 and 5.
GET #channel,R
Get reads record number R stored in a random access file opened using OPEN.
It then loads this record into the field strings created by field. These
strings can now be manipulated in the normal way.
PORT (#channel)
The PORT function tests to see if an input device connected to a channel
is waiting for you to INPUT some information from it. If the channel is
ready to output some information the the function will return -1 (true)
else it will return 0 (false).
The Printer
LLIST
Functions the same as LIST.
LPRINT
As PRINT
LDIR
Lists the current directory to the printer.
LISTBANK
Prints a list of the current banks to the printer.
HARDCOPY
Same as [alt+help].
WINDCOPY
Prints out the text in the current window.
Directories
DIR [path$][/w]
Lists all the files on the current disc. If the optional path$ is specified,
only the files which satisfy a certain set of conditions will be displayed.
This path$ can contain any one of the following six parts:
Ths name of a drive terminated by a [ : ].The name of a folder to be
listed(enclosed between [ \ ] characters.A string of characters which will
be matched in every filenameA [ * ] Denoting that any string will do.A
[ ? ] Which automatically matches with any single character in filename.A
[ . ] Which separates a filename from an extension.If the optional /W is
added then the files will be listed across the page. DIR$ Set or return
the current directory used for all disc accesses.
DIR FIRST$(path$,flag)
This function returns a string containing the name and parameters of the
first file on the disc which satisfies the conditions in the pathname path$.
The flag contains a number of binary bits which indicate the type of files
to be searched for. The format of the flag is:
Bit 0 Normal read/write filesBit 1 Read only filesBit 2 Hidden filesBit
3 Hidden system filesBit 4 Volume labels (The name of the disc)Bit 5 FoldersBit
6 Files which have been written to and closed
If you aren't sure which type of files you want to list, you can find
all the files on the disc by setting the flag to -1. If no file exists
on the disc matching your specifications, the DIR FIRST$ will return a
null string. Otherwise it will hold the following 45 character parameter
block:characters usage0-12 filename13-21 length of file22-32 date file
saved33-41 time file saved42-45 file type
DIR NEXT$
Returns the next file found using the path specified in DIR FIRST$ and
results in the same data block being returned if a match is found. Can
only be used after DIR FIRST$. As before, no string found returns a null
string, indicating that there are no more files in the current path.
PREVIOUS
Moves the current path up one directory.
DRIVE
Returns or Sets the current drive number 0=A & 1=B.
DRIVE$
Returns or sets the current drive letter "A" or "B"
DRVMAP
Holds a binary number denoting the drives currently connected. Each bit
represents the status of one of the drives. If the bit at a particular
position is set (1) then the appropriate drive is connected to the computer.
eg:Bit 0 = Drive ABit 1 = Drive BBit 2 = Drive C Note that DRVMAP always
returns a minimum of two drives even if only one drive is connected.
DFREE
Holds the amount of free space remaining on the disc.
MKDIR folder$
Create a folder on the disc with the name folder$.
RMDIR folder$
Deletes an empty folder from the disc.
KILL file$
This function deletes a file from the disc. If file$ contains the characters
[ * ] or [ ? ] a series of files will be erased.PERMANENTLY !
RENAME old$ TO new$
If a file already exists with the name new$ an error will be generated.
Trigonometric Functions
DEG(a)
Converts angles expressed in radians to degrees.
RAD(a)
Converts angles expressed in degrees to radians.
SIN(angle)
Calculates the sine of a angle. Always returns a floating point number,
so if you wish to assign the returned value to a variable, this must always
be of the double precision type.
COS(angle)
Returns the cosine of an angle. All angles are measured in radians. TAN(angle)
Returns the tangent of the angle.
ACOS(number)
Takes a number between -1 and +1 and returns the angle in radians ASIN(number)
As for ACOS
ATAN(number)
Generates the arctan of number.
HSIN(angle)
Returns the hyperbolic sine of angle. HCOS(angle) Returns the hyperbolic
cosine of angle.
HTAN(angle)
returns the hyperbolic tangent of angle. PI Returns the constant ¶.
Mathematical Functions
LOG(Y#)
Returns the logarithm in base 10 (log 10) of y# as a double precision number.
LN(y#)
Calculates the natural or Naperian logarithm of y#.
EXP(y#)
Returns the exponential of y# as a double precision number.
SQR(y)
Returns the square root of y.
ABS(y)
Returns the absolute value of y, ignoring the sign of the number. INT(y#)
Returns the integer value of y.
SGN(y)
Returns the sign of a number as follows.y=-1 Number is negativey=0 Number=0y=1
Number is positive
MAX(x,y)
Returns the largest of the two expressions. x and y Can be numbers or strings
of characters as long as both are not mixed in one instruction.
MIN(x,y)
As for MAX but returns the smallest value.
SWAP(x,y)
Swaps the data between two variables of the same type.
DEF FN name[(variable list)]=expression.
name is the name of the function you wish to define.variable can be any
list of variables separated by commas. These variables are local to the
function. Any variables you use in the function will be automatically substituted
for the appropriate local variables whenever necessary. Also note that
variables of different types can be mixed.
FN name[(variable list)]
Used to call a function defined with DEF FN.
RND(y)
Returns a number between 0 and y inclusive. If y<0 then the last
number generated will be returned again.
LET
Assign a value to a variable.
FIX(n)
This fixes the precision of any real numbers which are to be printed on
the screen. There are three possibilities:If 0 < n < 16 Then n denotes
the number of figures output after the point.if n > 16 the printout will
be proportional and trailing zeros will be removed in n < 0 Then all
floating point numbers will be output in exponential form, and the absolute
value of n will determine the number of digits after the decimal point.
UPPER$(n$)
Converts the string in n$ to upper case.
LOWER$(n$)
Converts the string in n$ to lower case. FLIP$(n$) Reverses the order of
the characters in n$. SPACE$(n) Creates a string of n spaces.
STRING$(a$,n)
Creates a string of n characters using the first character of the string
a$.
CHR$(n)
Creates a string containing the character with the Ascii code n.
ASC(a$)
Returns the Ascii code of the first character in the string a$.
LEN(a$)
Returns the length of the string a$.
VAL(x$)
Returns the value of a number stored in x$. If x$ does not contain a number
then the VAL will be zero.
STR$(n)
Convert a number n to a string of characters.
TIME$
Holds a string containing the current time. Can be set using the format
"HH:MM:SS".
DATE$
Holds a string containing the current date. Can be set using the following
format: "DD/MM/YYYY".
FILESELECT$
This feature enables you to call up a dialogue box to select a file on
a disc. The syntax of the function is:
f$=FILE SELECT$(path$[,title$[,border]])
path$ can be any string containing the search pattern which will be used
to display the possible files.title$ Is a string containing the title of
the dialogue box.border Is a number from 1 to 16 denoting the border style
which is to be used After completion of the dialogue, FILE SELECT$ returns
either the name of the file or an empty string if the QUIT option was chosen.
Machine Level Instructions
HEX$(n)
Converts a number to a string of characters in hexadecimal notation.
HEX$(n,x)
As above, but only uses the first n digits. n can range from 1-8.
BIN$(x)
Generates a string of binary digits equivalent to the number x. As with
HEX$, you can choose whether to generate all the digits or any number of
digits between 1 and 31.BIN$(x,y).
ROL x,y
Rotates a number y left by x places. The bit going off the left appears
on the right. The default word length is longword. To force a shorter word
the size can be specified as follows: ROL.W and ROL.B. Note that this function
expects the number to be shifted to be a simple variable and not an expression.
ROR x,y
As for ROL but the number is rotated to the right.
BTST(x,y)
Tests the bit at position x in the variable y. Returns a true for a bit
that is set and a false for a bit that's clear. As for ROL and ROR the
number to be tested must be a simple variable.
BSET(x,y)
Sets the bit at position y to 1 in the variable x. x must be a simple variable.
BCHG(x,y)
Inverts the bit at position y in the variable x.
BCLR(x,y)
As for BSET except the bit is cleared.
PEEK(address)
Returns the value of the byte at address.
POKE address,x
Sets the value at address to the value x.
DEEK(address)
Two byte version of PEEK. address must be even.
DOKE address,x
Two byte version of POKE. address must be even.
LEEK(address)
Four byte version of PEEK. address must be even.
LOKE(address,x)
Four byte version of POKE. address must be even
VARPTR(variable)
Returns the address of variable as follows:Integers Returns the location
of the value of the variable.
Real numbers Returns the location of two long words which contain the
value of the variable in the IEEE double precision format.Strings Points
to the first character of the string.
COPY start,finish TO destination
Moves a block of memory from start to finish to location starting at destination.
All these addresses must be even.
FILL start TO finish,longword
Fills the memory block start to finish with the value contained in longword.
Addresses must be even. It is possible to use the number of memory BANK
as start or finish.
HUNT(start TO end,a$)
Searches through the memory for a string a$ in the block start to finish.
On completion of the search either 0 or the location of a$ will be returned.
WAIT x
Suspends a Basic program for x 50ths of a second. Any functions which use
interrupts, such as MOVE and MUSIC will continue to work, with the sole
exception of ON MENU GOTO.
TIMER A
reserved variable incremented once every 50th of a second.
NOT(x)
This function inverts every bit of variable x.
Miscellaneous Instructions
REM
All text on a line entered after this statement will be ignored.
DATA variable list
The variable list can be any mixture of variable types and expressions
which must be separated by a comma.
READ
list of variables Standard Read function.
RESTORE line
line can be a line number or an expression which will be regarded as evaluating
to a line number. If this is not the case and the line number does not
exist then an error will be generated.
TRUE
This function returns a value of -1 which is used by all the conditional
operations such as IF...THEN and REPEAT...UNTIL to denote TRUE.
FALSE
Whenever a test is made such as X>10, a value is produced. If the condition
is true then this number is -1, otherwise it is 0. The FALSE function therefore
corresponds to a value of 0.