User manual
For SPECTRUM users
Note: the '^' character represents the up arrow symbol in Spectrum/Timex character set (Symbol Shift + H).
First Edition 1984
(C) T.O.S., Copyright TIMEX PORTUGAL Ltd.
TMX PORTUGAL Ltd. Apartado 2
2825 Monte da Caparica
TIMEX DISK OPERATING SYSTEM
------------------------------------------------------------------------------
CHAPTER - CONTENTS -
------------------------------------------------------------------------------
1 INTRODUCTION
------------------------------------------------------------------------------
1.1 Introducing TOS
1.2 About this manual
------------------------------------------------------------------------------
2 SETTING UP
------------------------------------------------------------------------------
2.1 Unpacking and Setting up
2.2 About the diskettes
2.3 Expanding the system
------------------------------------------------------------------------------
3 TOS - Part I
------------------------------------------------------------------------------
3.1 Using TOS commands
3.2 Getting started
3.3 CAT * - to catalogue disk contents
3.4 Filenames - what is in a filename
3.5 FORMAT *
3.6 LOAD * / SAVE *
3.7 Using LOAD * / SAVE *
3.8 MERGE *
3.9 TEMPLATES
3.10 ATTR *
3.11 ERASE *
3.12 LET *
3.13 MOVE *
3.14 Using MOVE * ERASE * LET *
3.15 START- to create start up files.
------------------------------------------------------------------------------
4 DIRECTORIES PATHNAMES - TOS Part II
------------------------------------------------------------------------------
4.1 The tree structure
4.2 TOS DIRECTORIES
4.3 The PATHNAME
4.4 Using TOS PATHNAMES
4.5 DIM *
4.6 GOTO * / ^ / : LIST *
4.7 GOSUB * / DRAW *
4.8 Using the Demo disk
4.9 ATTR * LET * MOVE * ERASE * LOAD * SAVE *
4.10 Using two or more drives.
------------------------------------------------------------------------------
5 RANDOM ACCESS and SEQUENTIAL FILES
------------------------------------------------------------------------------
5.1 Files
5.2 Channels
5.3 OPEN #*
5.4 LIST *#
5.5 RANDOM and SEQUENTIAL access files
5.6 RESTORE *
5.7 CLOSE #*
5.8 Fast and slow channels
------------------------------------------------------------------------------
6 SERIAL COMMUNICATION PORTS
------------------------------------------------------------------------------
6.1 The SCP's
6.2 FORMAT * a Serial Communication Port - configure
6.3 File transfer via Serial ports
6.4 OPEN #* and CLOSE #* commands with the SCP's
6.5 CLOSE #*
6.6 LIST *#
6.7 RESTORE *
------------------------------------------------------------------------------
APPENDICES
------------------------------------------------------------------------------
APPENDIX A - TOS COMMAND SUMMARY
APPENDIX B - ERROR REPORTS
APPENDIX C - UTILITY PROGRAMMES
APPENDIX D - RS232C LINK UPS
APPENDIX E - ERROR TRAPPING
APPENDIX F - MACHINE CODE TIPS
------------------------------------------------------------------------------
CHAPTER 1
------------------------------------------------------------------------------
INTRODUCING the TIMEX OPERATING SYSTEM (TOS)
------------------------------------------------------------------------------
The addition of disk drives to the SPECTRUM creates an immensely powerful system, and TOS - the disk operating system especially developed by Timex - gives you the power from within your BASIC programme that you have always wanted, but never believed would be available.
The secret lies in the controller which, controls the operation of the disk drives, and it is here that the TOS operating system resides. The controller is a separate computer having its own Z8OA Central Processor, as well as its own internal memory and input/output facilities. Every time a TOS command is issued it passes straight to the controller which then executes the instruction, Placing no overhead on the SPECTRUM, and of course is not dependent an any hardware limitations of the SPECTRUM, such as available memory.
The disks are the lastest in micro floppies, using very high density recording medium, giving on the standard floppy 160K free an each side of the disk providing 320K of disk space per drive.
The controller and TOS have been especially designed around the need to communicate. The controller has two serial communication ports which can be be configured to suit almost any type of protocol you are likely to need. This means that apart from being able to communicate with TOS users, you will be set to 'talk' to other users, on a variety of computers with a standard RS232C serial port. Other peripherals such as modems, printers, plotters or any device that can be coupled to a serial port can also be connected to these.
1.2 ABOUT THIS MANUAL
The manual has three separate sections.
The first contains enough information for you to set up and begin working with TOS.
The second goes through some of the more subtle ways of applying TOS in relation to the use of tree directory structures, random access and sequential files, and concludes with a chapter on the use of channels and serial communication ports.
The third part is a series of appendices for more specialised reference, and a quick reference guide to TOS.
Information about the utility programmes included an your demo disk are explained in this section.
------------------------------------------------------------------------------
CHAPTER 2
------------------------------------------------------------------------------
2.1 UNPACKING AND SETTING UP
------------------------------------------------------------------------------
Unpacking your system you will find: Disk drive unit
Controller
Power supply
Manual
Diskette
Set up the system as follows:
-Switch the power OFF to your SPECTRUM computer.
-Plug the interface into the rear edge-connector of the SPECTRUM.
-Connect the "D" plug of the controller to the interface.
-Connect the ribbon cable from the controller onto the disk drive.
There is a white mark on the ribbon plug witch should be pointing upwards, placing the red edge of the cable on your left as you look at the socket. The plug at the end of the cable must always be connected to drive A.
-Connect the power supply up as follows:
Check that the ON/OFF switch at the rear is off "0"
Plug the power leads into the disk drive and controller
Connect the mains plug
-Before turning on and inserting your diskette please read the section "about the diskettes".
-If you are using more than one disk drive refer to the section following on "Expanding the system".
If you are using a printer that normally plugs onto the SPECTRUM rear edge-connector you will need to connect the optional "T" connector between your SPECTRUM and the interface. The interface uses all the address lines on the port and needs to have more lines than are available from plugging into the back of the normal printer connecting plug.
If you are using a printer that has a standart RS232C interface, it may be connected to one of the two serial communications ports on the controller. Such leads are avaiable from Timex to plug into the controller in the relevant appendix of this manual.
------------------------------------------------------------------------------
2.2 ABOUT THE DISKETTES
------------------------------------------------------------------------------
The diskettes are made of a flexible mylar sheet coated with magnetic material, and are onclosed in a plastic casing, which has a shutter to protect the recording media. This shutter is automatically opened when the disk is inserted in the drive, and is the point where the read/write head of the disk drive is positioned. The disks have two sides, and are double density, and when used with this system have a formatted (meaning usable) capacity of 160K per side, giving in all 320K per drive.
The disks are very reliable, but some basic precautions use must be taken:
-Do not expose the disks to heat or direct sunlight
-Keep away from strong magnetic fiels, e.g. transformers.
-Do not open the shutter or finger the magnetic surfacve
-Keep away dust that could reach the recording surface.
The disks can be write protected by using the small plastic tabs. You can protect either side A or B or both by switching the two tabs on the disk. The creation of a hole by moving the tab will write protect the revelant side of the disk. Where the tab blanks off this hole the disk is not write protect.
------------------------------------------------------------------------------
2.3 EXPANDING THE SYSTEM
------------------------------------------------------------------------------
The basic configuration with a single disk drive can be upgraded to a total of four disk drives: A,B,C,D. The first one is A and each additional drive is assigned a letter as far as D.
Using more than two drives necessitates the use of a second power supply and a second cable from the controller to the drives.
The initialisation of the disk drives from the factory is for use as A drive. You will need to configure further disk drives yourself, as B, C, or D, depending on your system. You do this as follows:
-Unscrew the 4 screws on the base of case which hold the drive assembly in position. Remove the drive assembly from the case. The blue capped IC (integrated circuit) in a socket near the edge-connector of the drive marked R1 is only needed in drive A, for other drives it has to be removed. There is a jumper marked J01 which has to be connected corresponding to the drive designation using the following values: A=0, B=1, C=2, D=3. As you configure a new drive remember to label it with the drive letter an the front to the drive for easy identification. From the outside of the drive you can check the designation by looking into the rear edge connector. Under the word 'interface' You will see the small connector in one of 4 Positions, the leftmost position corresponds to A, and the right hand Pins for D.
Figure ..1.
If you are in doubt or difficulty contact your dealer.
------------------------------------------------------------------------------
CHAPTER 3
------------------------------------------------------------------------------
3.1 USING TOS COMMANDS
------------------------------------------------------------------------------
The way of accessing the TOS commands is familiar to those used to the SPECTRUM BASIC's use of keywords. All the TOS commands use existing keywords, but they are followed by an *(asterisk), so that LOAD becomes LOAD *.
TOS is a disk operating system: TOS commands are designed so that you can LOAD and SAVE with the Disk Drives in a way similar to that of cassettes.
The beauty of TOS is that it does not interfere with the existing instructions relative to the cassette, so that you are still free to use your cassette and disk drives at the same time, and even from within the same programme. You need not change your existing programmes when using TOS, but you will need to use LOAD * and SAVE * to transfer the programmes to and from the disks (in much the same way you would for a cassette). The syntax is essentially the same apart from the '*', which is there to activate TOS.
Instructions can either be executed directly from the keyboard or from within the programme like any other BASIC instruction. TOS therefore becomes an extension of the SPECTRUM BASIC, with all the disk and file handling facilities of TOS acting as extended BASIC functions.
The next section deals with the TOS instructions. There are two ways instructions can be executed: either directly from the keyboard (referred to as commands), or from within a programme (referred to as statements). Throughout the manual - in relation to TOS - the terms command and statement will be used in this context.
The term 'file' includes all types of programmes and data files, and no special distinction is made unless applicable.
Knowledge of the SPECTRUM keyboard and SPECTRUM BASIC is assumed. Any doubts may be clarified by referring to the SPECTRUM manuals
------------------------------------------------------------------------------
3.2 GETTING STARTED
------------------------------------------------------------------------------
The disk that comes with the system contains the demonstration programmes on side A and side B has nothing on it. If you look at the disk you will see that side A has been write protected using the plastic tab. Side B is not write protected, and is for you to use. The only copy of TOS you have is on side A, so make sure that the disk remains write protected. Side B will have to be formatted to be used, and is explained in section 3.4.
With the system set up you can now switch on the current using the power switch on the back of the power supply in the '1' Position.
Insert the disk labelled TOS in the drive and the system will 'BOOT'. The red light on the drive will flicker until finally it goes off. TOS is then ready for use. There is the controller reset button, which resets the whole system or the reset button on the interface, to reset the SPECTRUM.
When you reset the controller TOS will be 'BOOTED'. There will not be the normal message an the screen that appears when you turn on the SPECTRUM by itself when not using TOS.
There is a special kind of boot, described in section 3.15 that allows the automatic execution of a start up programme on your SPECTRUM.
CAUTION Do not power up the system with the disk inserted in the drive. It you stock the system, the power supply should be on the top Never prevent air circulation to the power supply.
------------------------------------------------------------------------------
3.3 CAT * - catalogue disk directory contents
------------------------------------------------------------------------------
Unless a cassette is labelled properly there is no way of knowing what programmes it contains without loading the programmes into the computer. TOS has a special directory of each file on the disk, together with information about where it is located on the disk, the size of the file, and other information, some of which is useful only to the operating system, but some of which is displayed as part of the listing appearing on the screen as a result of executing the CAT * instruction.
Using side A of your demo disk type in the command: (Side A is accessed by placing the disk into the drive door with side A facing upwards)
CAT * followed by enter
A listing of the disk directory contents will appear. Notice that you can stop the SCROLLING at any time using the S key and resume using the Q key. Try it. This is common to many TOS commands.
:DEMO
Level 0 Drive A
Name Typ Size Alloc S P
-------------------------------
HELP BAS 11087 11K P
MATHS DIR 3187 4K P
FUN DIR 6651 9K P
UTIL DIR 3075 7K P
FILING DIR 1070 2K P
MAX 140K CUR 33K REM 107K
0 OK, O:1
------------------------------------------------------------------------------
3.4 FILENAMES - what is in a filename
------------------------------------------------------------------------------
Referring the directory output from the CAT * instruction of the previous page, you will see the columns contain the filename, the extension (type) of file, the file size in bytes, the disk allocation and finally two columns headed S and P, these are to indicate it the file is currently open, and if it is write protected.
The filename is a string of up to 8 characters, optionally followed by another string of up to 3 characters to indicate the file type. The filename and the extension must be separated by a .(dot). TOS treats the filename as a BASIC string and therefore it must be surrounded by matching quotes. It is possible to use symbols as well as digits and characters, although the symbol must be a single character not >= or keywords. The following symbols are used by TOS and must not be used: ".", "^", "?", "+".
TOS will automatically convert any file name to the upper case equivalent
examples:
"HELP.BAS" equivalent to: "hElp.Bas" or "help.bas"
"UTILITY.DIR"
The file type is useful for reference, the only extensions that have special meaning to TOS are the DIR and SCP extensions, used to identify the name of a directory or a communication channel.
TOS stores files in directories, but also allows a directory to be stored within another directory. The route to a file or the pathname, may be just the name of the file, but can include the name of the directories on the route to the file. Being able to specify pathnames in this way is a very powerful feature of TOS, and a chapter of the manual is devoted to it.
The size of the file is the number of bytes the programme will use in RAM (Random Access Memory) of the SPECTRUM plus 5 or 7 bytes for use of the system.
The disk is divided into tracks, which are in turn divided into sectors. These tracks and sectors are termed 'soft sectored', because they are written to the disk by software. This process of placing these tracks and sectors on the disk is called Formatting, and must be done before the disk can be used.
The disk allocation of a file relates to the number of sectors used. TOS allocates always a minimum of 1KB(1024 bytes) to a file.
The last two columns headed S & P indicate whether the file is open, and whether or not it is write protected.
Open meaning, that the file is currently open to be accessed from a programme. The P indicates that a file is write protected, this refers to the software facility within TOS, not the setting of the plastic tab or. the casing of the disk.
------------------------------------------------------------------------------
3.5 FORMAT * - prepare new disk to operate under TOS
------------------------------------------------------------------------------
Any disk has to have the sectors and tracks recorded onto it before it is used, most systems have other information placed on the disk as well. The way TOS operates is by being written itself to each side of a disk.
When the system is 'booted' up TOS is there and is transferred into the controllers memory.
This Process of preparing the disks for use in this way is called FORMATTING.
The syntax is:
FORMAT *"drive name" TO "disk name"
CAUTION: FORMAT * DESTROYS ALL OF THE DISK CONTENTS !
The only way to prevent a disk from being FORMATTED is to use the protection tabs on the disk .
This is the only TOS instruction where the Drive name, and disk name must be specified. The names of the four drives are A,B,C,D. Where only one drive exists it must be drive A.
The demonstration disk side A has all the demonstration programmes and the operating system TOS on the disk on side A. CAT *, the directory command, will show that there are files there. Side B is not FORMATTED, so will need doing straight away.
Side B is accessed by placing the disk into the drive door with side B facing upwards.
RESET : On the controller to reset TOS
Remark: Red light of disk A flashes on for a while then stops
Remark: The sign that TOS is being read from the disk, all o.k.
Remark: Turn disk over to side B
Enter : CAT *
Remark: Disk keeps spinning, but stops with error report
Remark: Error report: Hardware fault on disk DEMO
Remark: This occurs because the disk is not FORMATTED
The disk must have a name to be used for the FORMAT *, let it be Test. Follow the instructions to see how it is done.
Remark: turn disk over to side A
Remark: FORMAT * will clear all data from a disk, be careful
Enter : FORMAT *"A" TO "test"
Remark: TOS responds: Format disk in drive A (Y/N) ?
Enter : Y
Remark: Change disk and press ENTER
Remark: turn to side B
Enter : ENTER
Remark: This allows formatting with a one disk system
Remark: It takes about 30 secs to format
Remark: It stops through 40 tracks and then writes TOS across.
The system is written to the disk and uses up 16K of space on the disk. There is another 4k used by the directory for the disk. You can notice that the system is written to the disk last and takes place while the light is flickering at the very end.
To format the disk B the principle is exactly the same, except the drive name is disk B. If the disk name was 'NEWDRIVE', then the command would appear like this!
FORMAT *"B" TO "NEWDRIVE"
In this case there must be a system disk in drive A for the system to work, and there would be no delay for disk change, which is there to allow the change of disk needed to format a disk in a single drive system.
------------------------------------------------------------------------------
3.6 LOAD * / SAVE * - transfer between disk and RAM (memory)
------------------------------------------------------------------------------
LOAD * and SAVE * are similar to the standard LOAD and SAVE instructions of the SPECTRUM, except that a name must be specificied, and TOS treats all characters as upper case. LOAD *"" will produce an error report.
The LOAD "" of the SPECTRUM is useful when the name of the programme is not known. In TOS the CAT * command displays the directory of the files on the disk, making is easy to find the programme needed.
The same options of LINE, CODE, SCREEN$ and DATA exist
The syntax for SAVE * and LOAD * is the following:
SAVE * pathname LOAD-OPTION [n]
LOAD * pathname LOAD-OPTION
When the path in SAVE *refers to an existing file TOS prompts:
<> already exists
Supersede (Y/N) ?
A "Y" will overwrite the file <> whilst "N" will ignore the command. If the [n] option is used then TOS will carry out the command without prompting.
The OPTIONS are:
SAVE * pathname LINE number -save with auto run
LOAD * / SAVE * pathname SCREEN$ -save a screen
LOAD * / SAVE * pathname CODE start,length -save machine code
LOAD * / SAVE * pathname DATA array name () -save string array or numeric array
Try the following:
Remark: Using the demonstration disk in drive A SIDE A
Enter : CAT *
Remark: All the files in the directory displayed.
Enter : LOAD *"HELP.BAS"
Remark: The optional typ is separated by a .(dot)
Remark: To stop a programme use BREAK- [capshift space]
Enter : Press ENTER and then LIST
Remark: The programme listing appears on the screen.
Example Programme to generate a screen:
(linked to the exercise following)
10 REM TOS.BAS
20 PAPER 3
30 FOR I=1 TO 704
40 PRINT "$"
50 NEXT I
60 PAPER 6
70 PRINT AT 5,13;" TOS "
80 PRINT AT 13,12;" TIMEX "
90 PRINT AT 15,7;" OPERATING SYSTEM "
100 STOP
------------------------------------------------------------------------------
3.7 USING LOAD * / SAVE *
------------------------------------------------------------------------------
Using side B of your demonstration disk:
Enter : SAVE *"tos.bas" LINE 10
RESET : Using the reset button on the interface.
Enter : CAT *
Remark: The programme TOS.BAS should now be in the directory.
Remark: The SPECTRUM memory is clear.
Enter : LOAD *"TOS.BAS"
Remark: The Programme automatically runs.
Remark: The programme was saved using lower case.
Enter : SAVE *"TOS.SCR" SCREEN$
Remark: The screen memory image is saved as bytes in memory.
Remark: CAT * will confirm the screen has been saved.
RESET : Using the reset button on the interface.
Enter : LOAD *"TOS.SCR" SCREEN$
Remark: The screen memory address 16384, with 6912 bytes loaded.
Enter : SAVE *"TOS.COD" CODE 16384,6912
Remark: Save option of CODE start address,length
RESET : on interface
Enter : LOAD *"TOS.COD" CODE 16384,6912
Remark: Exactly equivalent to load with screen$-now you know why
Enter : CAT *
Remark: New screen !
Enter : SAVE *"TOS.SCR" SCREEN$
Remark: TOS prompts You.(answer no)
Enter : SAVE *"TOS.SCR" SCREEN$ n
Remark: No prompting ! "TOS.SCR" is overwritten.
The use of Arrays in BASIC is the main way of creating Data storage. TOS provides additional file handling capabilities in sequential and random access files. Data can still be saved in arrays using TOS.
The syntax for a string array named p$ which is to be saved as the date file 'name.dat' is:
SAVE *"name.dat" DATA P$() to load: LOAD *"name.dat" DATA p$()
Were the array numeric the syntax would only differ in the name for the array which would have no '$' after it.
Using the file type to indicate the type of data in the file, the right Load-option can more easily be chosen, avoiding the likelyhood of data type mismatch. E.g. a SCREEN$ type cannot be loaded using LOAD *'filename'.
------------------------------------------------------------------------------
3.8 MERGE * - merge one programme on another
------------------------------------------------------------------------------
The syntax is MERGE * pathname
This merges a new programme and its variables, specified by the pathname with the old programme in the SPECTRUM memory.
The new file must contain a BASIC programme and overwrites any of the programme lines or variables in the old programme with line numbers that conflict with the ones of the new programme. It is not possible to merge bytes or arrays .
RESET : On the interface
Remark: Use side B of Demo disk
Type : 40 PRINT "#";
Enter : SAVE * "TOS.OVL"
Enter : CAT *
Remark: Programme 'TOS.BAS' and 'TOS.OVL' are on disk
Remark: Going to overlay TOS.OVL onto TOS.BAS
Enter : LOAD *"TOS.BAS"
Enter : MERGE *"TOS.OVL"
Enter : Press ENTER
Remark: Line 40 is changed by the MERGE *
Enter : RUN
------------------------------------------------------------------------------
3.9 TEMPLATES - masks for any name / character
------------------------------------------------------------------------------
A template is similar to the 'Joker' in a pack of cards, because it can be anything. A template will allow a selection over a number of files, by for example selecting all those beginning with a particular character, or all those with a BAS type extension.
There are two templates characters or wildcards in TOS as follows:
+ (plus) replaces all the name, or type
? (question mark) replaces a character
A pathname with at least one of these characters is called a TEMPLATE
Selection of files could be done like this:
"+.+" -name and type masked
"+.BAS" -any name with BAS type
"+" -any file with no type
"C???????.+" -any 8 letter file starting with C
"C+" -File starting with C and no type
Templates are very useful for checking directories using CAT * to find a particular type or group of files. They can be used with the following instructions:
CAT * / LET * / ATTR * / MOVE * / ERASE *
Instructions needing a specific argument such as GO TO * cannot use TEMPLATES. Go to anywhere is meaningless!
------------------------------------------------------------------------------
3.10 ATTR * - protect / unprotect file
------------------------------------------------------------------------------
The ATTR * instruction sets the file attribute to 'protected' or 'unprotected' and to 'visible' or 'invisible' as required.
The syntax is:
ATTR * pathname p -to Protect a file
ATTR * pathname u -to Unprotect a file
ATTR * pathname i -to Hide a file
ATTR * pathname v -to Unveil a file
Templates are allowed to lock or unlock ranges of files. This protection is useful to prevent inadvertent erasure or altering of a file.
Files that are made invisible with this command will not be displayed when a CAT * is executed. 'Visibility' can be retrieved by using the ATTR * pathname v command.
Try the following:
Remark: use side B of the demo disk
Enter : CAT *
Remark: last col of directory is protect state
Remark: Programme 'TOS.OVL' is on the disk.
Enter : ATTR *"TOS.OVL"P
Remark: P does not appear in protect column straight away.
Enter : CAT *
Remark: Now the P appears showing the file is protected.
Enter : ATTR *"+.+"U
Remark: Unprotects all files
Enter : CAT *
Remark: All files are now unprotected nothing in last column.
Enter : ATTR *"+.+"p
Remark: All files are now Protected an side B of Demo disk.
Enter : ATTR *"+.+"i
Enter : CAT *
Remark: No files displayed by the CAT * command
Enter : ATTR *"+.+"v
Enter : CAT *
Remark: All files visible once more
------------------------------------------------------------------------------
3.11 ERASE * - erase file
------------------------------------------------------------------------------
When files are no longer needed the best thing to do is delete them the instruction for this in TOS is ERASE *.
The syntax is:
ERASE * pathname [n]
Templates can be used. ERASE * will not delete a protected file. TOS prompts you with the following response before taking action unless the [n] parameter is given, then it will be carried out without TOS asking, no prompt:
Erase < > Y/N ? (< > represents the file name)
Y will execute the command
N will stop the file from being erased
------------------------------------------------------------------------------
3.12 LET * - change name
------------------------------------------------------------------------------
This instruction to rename a file in TOS is: LET *
The syntax is:
LET * old Pathname TO new-pathname
TO is a keyword, and cannot be the characters TO separately.
Protected files can be renamed, where the protection is at the file level with the software. If the directory has been write protected, renaming would still be possible. However if the disk has been software write protected TOS will prevent renaming. Setting the hardware protection tab also prevents name changes.
TOS gives on error message explaining the protection level.
Trying to rename an open file or using templates will generate error messages from TOS.
------------------------------------------------------------------------------
3.13 MOVE * - copy source to destination
------------------------------------------------------------------------------
Creating copies of disks and programmes is an essential part of using a disk system. Important work, and programmes should be backed up.
If you are using a single disk system, you will need to use the utility programme, which is on your demo disk in order to create a copy of an entire disk. Details are in the appendix - Utility programmes.
A disk copy may be made where there are two drives by using the copy command and specifiying the target directory, into which the files are to be copied. This is dealt with in section covering directories in CHAPTER 4
The syntax is:
MOVE * source-name TO destination-name
Try the following:
------------------------------------------------------------------------------
3.14 USING - MOVE * / ERASE * / LET *
------------------------------------------------------------------------------
Remark: Using side B of the demo disk.
RESET : on the interface
Enter : CAT *
Remark: P in the last column indicates file is protected
Remark: Can a protected file be renamed?
Enter : LET *"tos.ovl" TO "renamed"
Remark: No obvious change - directory needs refreshing
Enter : CAT *
Remark: The name is now RENAMED with no type
Remark: The file is still protected with the name change
Enter : MOVE *"renamed" TO "tos.ovl"
Enter : CAT *
Remark: Now the original copied from the renamed is back
Remark: copying creates a duplicate of the file
Enter : ERASE *"renamed"
Remark: protected files cannot be erased
Enter : ATTR *"renamed"u
Remark: Unprotect the file
Enter : ERASE *"renamed"
Enter : CAT *
Remark: That did it
Enter : ATTR *"+.+"p
Enter : ERASE *"+.+"
Remark: TOS lists all the protected files not erasable
Enter : ATTR *"+.+"u
Enter : ERASE *"+.+"n
Remark: TOS erases all files without Prompt of Y/N
Remark: The Demo disk side B - all programmes erased
------------------------------------------------------------------------------
3.15 Start - creating start up files.
------------------------------------------------------------------------------
TOS allows you to create a start up file which is automatically loaded into your SPECTRUM and run every time you reset it (power up or RESET button on the interface).
To use this feature you must SAVE * your start up Programme with the auto run facility and call it 'START'. Now every time a reset is executed TOS will look for, a Programme named 'Start' in drive A if it exists then the SPECTRUM will run it.
Remark: To be able save the programme displace the disk protection tab.
Enter : Using side A of your diskette
Enter : 10 LOAD *"HELP.PAS"
Remark: SAVE *"start" LINE 10
Enter : Creating a programme named 'START'
Reset : CAT *
Remark: Using reset button an interface.
Remark: Help.bas runs automatically.
If you have a programme named 'START' and you want to temporarly avoid its execution use BREAK while pressing the reset button on the interface. If you don't wish to use it at all simply erase it.
Try the following 'START' programme:
10 CAT *
20 INPUT "Name of file to LOAD ? ";a$
30 LOAD *a$
------------------------------------------------------------------------------
CHAPTER 4
------------------------------------------------------------------------------
4.1 TREE STRUCTURE
------------------------------------------------------------------------------
A Tree structure has a stem linked directly to the root. There are branches which are directly linked to the root, but there are branches which grow out of other branches, and so on.
The path from a leaf to the root, may involve passing through several branches, on the way to the root.
The path may be very complex if the branch that the leaf is connected to is itself connected to other branches, but may also be very simple if there is a direct connection to the root via the stem.
The directory structure of TOS is analogous to the tree structure:
- There is a root directory which contains other directories.
- A directory may contain files and /or directories.
- Directories can be nested one within another.
- From any directory to a file (or directory) there is a specific route called, the PATHNAME
- A PATHNAME is a specified route of moves from a source directory through the tree structure to a file together with the filename.
- The PATHNAME can be the filename itself, when the file is within the source directory and no move is needed to reach it.
Note: Source directory does not mean root directory, but any directory which is the source of the path, in the PATHNAME.
The advantage of being able to name directories in this way means that the possiblity exists for grouping information or programmes into convenient divisions. When many files exist on a disk it is only necessary to CAT * that directory containing the file, thus avoiding the need to have several screens of files displayed.
Grouping file types under one directory, will make accessing them easier. For example if the BASIC programmes are in one directory and the machine language programmes are in another, then accessing and using the programmes is easier and leaves less chance of errors trying to LOAD * a programme with the wrong Load-Option. Including the extension type, whether BAS to represent BASIC or .COD to represent CODE or whichever extension is convenient to identify the file type, is useful, especially when large numbers of files are on the disk.
------------------------------------------------------------------------------
4.2 Introducing TOS with DIRECTORIES
------------------------------------------------------------------------------
It is important to identify the difference between the directory and the file. The directory contains the reference to where the file is rather like an index to a book does. TOS is organised in a hierarchic structure meaning that it is possible to have files and /or directories inside directories. The directories appearing just like any other files inside a directory, but they always have a DIR type extension to the name.
There are two special files with the extension SCP, these are serial communication ports, and are: CH_A.SCP and CH_B.SCP, these may also appear in the directory listing and are dealt with in the last chapter.
The structure of your system with the demonstration disk is, shown below:
Figure ..2.
TOS Provides various ways of moving around the directory structure as well as methods of creating, erasing, protecting, copying, and renaming a directory.
------------------------------------------------------------------------------
4.3 THE PATHNAME
------------------------------------------------------------------------------
The TOS use of PATHNAME allows access to any file on whichever disk, or directory that it is in.
The directory which is the one that TOS is currently at, is termed the default or current directory. When a command like CAT * is performed it uses as its argument the current directory name, and produces the listing of that directory.
The tree structure that TOS uses should be considered as an inverted tree, with the root at the top, and the branches coming down. This is so that moving 'up' the tree, involves moving back upwards to the root. Moving down involves moving through named directories towards the lower branches. Moving downwards the branches, provide alternative routes. This is why TOS will insist or, having directory names specified on the way down, but will accept '^' (an up arrow) as an instruction to move up, because on the way up there is only one way to go.
------------------------------------------------------------------------------
4.4 Using TOS PATHNAMES
------------------------------------------------------------------------------
TOS can use pathnames in the majority of the instructions such as LOAD *, SAVE *, MERGE * CAT *, ERASE *, MOVE *, ATTR *, DIM *, LET *. These instructions function in much the same way as they would using a filename, but have the additional options available through the added ability to work through the pathname, and so operate across the boundary of the directory.
There are several points to note about pathnames as follows:
-The pathname is a compound name, defining a path from the current directory to a file (or a directory).
-Directory names on the path must be separated by a colon (:).
-The root directory may be represented by a colon (:).
-Any pathname can be defined from the root directory by starting the pathname with a colon.
-Any pathname not starting with a colon will be from the current directory.
-The Pathname is treated as a BASIC string and is within quotation mark, and can be represented by string variables.
Referring to figure 2 of the directory structure in the demo disk, the pathname can be studied in relation to the following examples:
FILE -------------------- PATHNAME --------------
Calendar.bas ":DEMO:FUN:CALENDAR.BAS"
Hi-lo.bas ":DEMO:FUN:GAMES:HI-LO.BAS"
Roots.bas ":DEMO:MATHS:ROOTS.BAS"
The pathname consists of a 'Path' through the directories together with a target 'filename'. TOS helps you to know where you are by printing cut the 'path' to the current directory at the head of the directory listing. How ever far down a directory tree you go this information is always in the directory, together with the level of nesting of GO SUB * level of the directory.
------------------------------------------------------------------------------
4.5 DIM *
------------------------------------------------------------------------------
There are times that it is necessary to create files that are not for storing programmes or screens, but some other kind of information. The DIM * instruction is provided by TOS for this purpose.
The svntax is:
DIM * pathname
DIM * creates a file or a directory. The use of the path means that files can be created outside the current directory.
To create a directory the DIR extension must be included, letting TOS know it is a directory, otherwise a file would be created.
Using DIM * it is possible to create up to 16 directories an each side of the disk, that includes the directory corresponding to the disk itself. This means 15 now ones can be created, the structure is entirely up to the user. Attempting to create more then 15 will generate the error report: cannot create more directories.
Directories may be nested withing each other or directly under the disk's main directory, at the same level.
DIM * cannot be used to create an SCP (Serial Communication Port). Trying to do so would product an error report of wrong type.
DIM * cannot be used to create a file that already exists.
It a file 'newfile' exists then DIM *"newfile" would generate the error: NEWFILE already exists.
A similar conflict would occur trying to DIM *"newdir.dir" that already existed.
Creating a file of the same name as a directory is not allowed.
Attempting to open a file "newdir", without any type extension would still produce the error: NEWDIR already exists.
The pathname can be a string variable, and the DIM * instruction used as a programme statement as in the following example:
Two directories are opened using a direct command as follows:
DIM *"NEWDIR.DIR":DIM *"NEWDIR:DIR1.DIR"
10 REM Create files
20 LET a$=""
30 FOR i=1 TO 8
40 LET a$=a$+STR$ i
50 DIM *"newdir:dir1:"+a$
60 NEXT i
Remark: Use side B of disk, SAVE * the above programme
Enter : SAVE *"CREATE"
Enter : RUN
Enter : CAT *"newdir:dir1"
Remark: In directory "dir1" are:1, 12, 123, 1234,......,12345678
Remark: All the files are created with size zero
------------------------------------------------------------------------------
4.6 GO TO * / ^ / : / LIST *
------------------------------------------------------------------------------
The default directory can be changed to another directory by usin the GO TO * instruction.
The syntax is:
GO TO * Pathname
A special instruction exists to move up through the directory structure which is;
GO TO *"^" -move up one directory level
GO TO *"^^" -move up two directory levels
Any number of levels can be moved up in this way, but there is a short form of returning to the top (the root) which uses a colon and is as follows:
GO TO *":" -goes to the root directory
The Place you are in TOS is always stated at the top of the directory. TOS allows that information to be displayed by itself using the LIST * command, along with your directory location.
GO TO * and LIST * may be used as a programme statements.
The pathname may be a string variable.
Remark: Using side A of your demo disk.
Enter : CAT *":"
Remark: The physical resources of your system are displayed starting with the name of the disk In drive A followed by the two SCP's.
Remark: Another way to display the root is,
Enter : GO TO *":"
Enter : CAT *
Remark: Suppose You just wanted to know the size of the file 'HI-LO.BAS'
Enter : CAT *"DEMO:FUN:GAMES:HI-LO.BAS"
Enter : CAT *
Remark: Your current directory is still the same.
Remark: If you wanted to make 'GAMES' current directory
Enter : GO TO *"DEMO:FUN:GAMES"
Remark: To know information about "HI-LO"
Enter : CAT *"HI-LO.BAS"
TOS allows you to change your current directory to another drive without knowing the disk name. The syntax is:
GO TO *"DRIVE NAME"d
Where the 'DRIVE NAME' can be A, B, C, or D. Specifiyng a pathname is not allowed when using this facility. Refer to Section 4.9
------------------------------------------------------------------------------
4.7 GO SUB * / DRAW *
------------------------------------------------------------------------------
It is very useful to go to a directory perform whatever instructions are needed and return back to the source directory.
TOS allows this using the GOSUB * instruction followed by the DRAW * instruction. The process is very similar to a subroutine call in BASIC. TOS uses a directory stack, which holds information on the level of nesting of these calls. TOS allows 8 levels of nesting of subroutine calls to directories in this way.
The syntax is:
GO SUB * [pathname]
The pathname between brackets means that it is optional.
GO SUB * is used in conjunction with DRAW * which causes a jump back to the original directory. The level of GO SUB * nesting is displayed at the head of the directory listing produced by CAT *.
It does not matter which directory is current it will always be level 0, unless a GO SUB * has been executed. The level refers to the level of nesting on the stack. Every time a DRAW a is executed, the level drops by 1. An error will result from trying to DRAW * from level 0: cannot return from level 0.
The advantage of using GO SUB a instead of the straight GO TO a instruction is that TOS automatically keeps track of your route and will DRAW * you to where you started, and the way back requires no argument, just DRAW *. GO TO * would require the path specified for the route back. You can also use '^' to move up levels of directories.
LIST * displays the contents of the directory stack, hence for all the levels the following information:
PATHNAME, LEVEL, and DRIVE ()
Remark: Using side A of your demo diskette
Remark: You want to save your current directory in the stack for later use but you want to remain in that directory.
Enter : GO TO *":DEMO:FUN" or GO TO *"DEMO:FUN" it you are still at the 'ROOT'
Remark: Makes 'FUN' your current directory
Enter : LIST *
Enter : GO SUB *
Remark: No pathname. Current directory saved an stack.
Enter : LIST *
Remark: The current directory is the some but the directory level has been incremented.
Enter : GO TO *":DEMO:MATHS"
Enter : CAT *
Enter : DRAW *
Enter : LIST *
Remark: You got bock to your first directory.
Like with the GO TO * command this instruction also permits the usage of the d Parameter (GO SUB *"drivename"d) which will enable you to change drives without specifying the disk name.
------------------------------------------------------------------------------
4.8 DEMO DISK
------------------------------------------------------------------------------
The Demo disk contains programmes on side A that should be used for the following study of the directory structure.
The pathname making use of nested directories will be used, together with the proceeding set of instructions.
Remarks on how compound pathnames differ from pathnames with no 'path' in relation to the instructions introduced in chapter 3 will be dealt with at the end of the next section.
Try the following:
Remark: Using side A of the Demo disk
Enter : GO TO *":"
Remark: go to the root directory
Enter : CAT *
Remark: DEMO.DIR
Remark: CH_A.SCP
Remark: CH_B.SCP
Enter : GO SUB *"DEMO"
Remark: Going down the tree, but can easily returns
Enter : LIST *
Remark: Tells us where we are
Enter : CAT *
Remark: See what is available:
Remark: Help.bas only Programme, rest are directories
Enter : LOAD *":DEMO:HELP.BAS" or simply LOAD *"help.bas"
Remark: using a compound pathname in LOAD *
Remark: Running help, you find it is a TOS summary
Remark: A programme can be stopped using BREAK
Enter : CAT *
Remark: using LOAD * did not change the LEVEL from 1
Enter : GOSUB *"FUN"
Enter : CAT *
Remark: level 2, & pathname on top of directory
Remark: What about a game!
Enter : GOSUB *"GAMES"
Enter : CAT *
Remark: play dice!
Enter : LOAD *"DICE.BAS"
Remark: When wou have had enough BREAK {CAPSHIFT SPACE}
Remark: How to go and got help again
Enter : LOAD *":DEMO:HELP.BAS"
Remark: After finishing see where we are
Enter : CAT * or LIST *
Remark: We did not move from the current directory
Enter : DRAW * followed by LIST *
Remark: each DRAW * moves down 1 level
Enter : Using GO TO *"^^" or : would got back to root
Remark: use GO TO * instead of GO SUB * doing it again
------------------------------------------------------------------------------
4.9 ATTR * / LET * / MOVE * / ERASE * / LOAD * / SAVE *
------------------------------------------------------------------------------
The way these commands operate with files, is similar to the way they operate using directories, however there are differences, based on the fact that a directory can contain a file. This means that operating on a directory will affect the file. Some instructions cannot be used in the same way with directories.
ATTR *: can be used to protect, unprotect, veil or unveil directories in a similar way that it can be used with files. As an example;
ATTR *"Newdir:dir1:+.+"v
Will unprotect all the files in 'dir1'
LET *: Directories can be renamed just like files, but only when there are not any files currently open. As an example:
LET *":Disk1" TO ":Work"
will rename directory 'Disk1' to 'Work'.
MOVE *: The copying function cannot be used to copy a directory. However the files from within can be copied freely from one directory to another. A utility backup programme exists which will perform the function of a disk Copy When needed. This programme is on the disk that you received with TOS, and its functioning is explained in the appendix C.
A file can be copied from one directory to another like this:
MOVE *"create" TO "newdir:create"
MOVE * can also be used with SCP's, copying to then and from them just like other files. You can even copy from one SCP to the other, which could be useful for echoing the input from CH_A to CH_B could be used in testing a device equipped with an RS232C interface, like a video terminal or other computer.
MOVE *":CH_A" TO ":CH_B"
A File can be 'sent' to an SCP using MOVE * as follows:
MOVE *"Tos.bas" TO ":ch_b"
CAT *: Can be used simply by adding the full pathname as follows:
CAT *"newdir:dir1" to list all the files on "dir1"
ERASE * can be used in much the same way as with files, except you cannot erase the names defined in the root, like the actual name of the disk and the SCP's. Erasing a directory will erase all the files within it, but if a directory contains another directory it cannot be erased. All files have to be closed before a directory can be erased, or indeed even a file that is open cannot be erased. If there are files within a directory that are write protected, then the directory cannot be erased until they have been unprotected. You can ERASE * unprotected files inside protected directories.
There is an option using ERASE * that allows files to be erased without offering the Y/N prompt that is normal. This is using the n option, which works like this:
ERASE *"+.+"n -no prompting
ERASE *"+.+" -will give Y/N choice for each file
LOAD * / SAVE * can be used in exactly the same way as with a single file except including the full pathname. This way you are able to save or load programmes from any of the directories in the system, from the current directory.
SAVE *":NEWDIR:DIR1:CREATE" -saves the programme in dir1
LOAD *":NEWDIR:DIR1:CREATE" -to load it
Try the following:
Remark: Using disk B. With the program 'CREATE' we generated 8 files with numeric names in section 4.5
Enter : ERASE *"NEWDIR"
Remark: Can not ERASE * a directory that contains directories.
Enter : GO TO *"NEWDIR"
Enter : CAT *"DIR1"
Remark: Create another directory and copy all files into it
Enter : DIM *"DIR2.DIR"
Enter : MOVE *"DIR1:+.+" TO "DIR2"
Enter : CAT *"DIR2"
Remark: All the files in dir1 copied to dir2
Remark: Protect/ unprotect dir1 and files then erase them!
Enter : ATTR *"DIR1"P
Enter : ATTR *"DIR1:+.+"P
Enter : CAT *: CAT *"DIR1"
Enter : ERASE *"DIR1"
Enter : ATTR *"DIR1"U
Remark: The directory is unprotected, but files are Protected
Enter : ERASE *"DIR1:+.+"
Remark: Files need to be unprotected for erasure
Enter : ATTR *"DIR1:+.+"U
Enter : ERASE *"DIR1:123456??"
Enter : ERASE *"DIR1:??3+"
Remark: Study selective erasure using templates
Enter : ERASE *"DIR1:+.+"
Remark: Renaming a file/dir
Enter : LET *"DIR2:12" TO "DIR2:RENAMED"
Enter : CAT *"DIR2"
Remark: Rename a directory
Enter : LET *"DIR2" TO "DIRNEW"
Enter : CAT *"DIRNEW"
Enter : ERASE *"DIRNEW"
Enter : CAT *
Remark: Erasing a directory will erase the files within it
Enter : ERASE *"DIR1"
Enter : GO TO *"^" -Make test your current directory
Enter : ERASE *"DIRNEW": CAT *
Enter : ERASE *"CREATE"
Remark: Side B of demo disk now empty : Use side B for CHAPTER 5 examples.
------------------------------------------------------------------------------
4.10 USING TWO OR MORE DRIVES
------------------------------------------------------------------------------
As you know the ROOT represents the physical resources of your system. You can connect up to 4 drives (A to D) as wall as the two communications ports (CH_A and CH_S)-see section 2.3. Knowing the names of your disks (to do that you CAT * the ROOT) you can access other drives just by specifying a pathname starting at the ROOT or at your current directory.
To access the other drives treat them as if they were directories placed immediately under the ROOT. So if you wished to move 'say' to the disk in drive B you could type:
GO SUB * or GO TO *":Name of drive B disk'
Try the following example;
Remark: For users with more than one drive
Remark: Using side A of demo disk and a blank disk in drive B
Enter : FORMAT *"B" TO 'NEW'
Enter : Y
Remark: Formatting drive B
Enter : CAT *":"
Remark: You now have two disksEnter : DIM *":NEW:MATHS.DIR"
Enter : MOVE *"MATHS:+.+" TO ":NEW:MATHS"
Enter : CAT *":NEW:MATHS"
Enter : GO SUB *
Remark: Use of GO SUB * without a pathname.
Enter : GO TO *"NEW:MATHS"
Enter : CAT *
Remark: Your current directory is MATHS in drive B
Enter : DRAW *
Enter : CAT *
Remark: Return to previous directory
Enter : LOAD *":NEW:MATHS:ROOTS.BAS"
Remark: Now try changing your, current directory to MATHS in disk B and LOAD *"LINEAR.BAS"
Try the following to understand the way of changing drives without knowing the names of the disks.
Enter : GO TO *":DEMO"
Remark: Your directory is now drive A
Enter : GO TO *"B"d
Enter : CAT *
Remark: Your current directory is now 'NEW' in drive B.
Remark: Try to go back to drive A using GO SUB *"A"d
------------------------------------------------------------------------------
CHAPTER 5
------------------------------------------------------------------------------
5.1 FILES
------------------------------------------------------------------------------
A file may be thought of as a collection of pieces of information bound to the same name. Until now the concept of a file as a whole unit has been used. A BASIC programme is an example of a such a file. Using the SPECTRUM in the traditional way, data for example would be contained in an array, to access any data the whole file would be loaded and accessed as a whole.
A feature of TOS is that it permits the reading of a part of a file without the need to read the whole file. This feature is especially useful in preparing large data files where individual records from the file are to be accessed, as needed for example, in data base, stock control applications, and other business applications. This allows the creation of files of any size no longer limiting your applications to the size of the SPECTRUM memory.
------------------------------------------------------------------------------
5.2 CHANNELS
------------------------------------------------------------------------------
TOS accesses (reads or writes) files through channels. A channel is a number associated with a file that you use to refer to it in the instructions PRINT * (which writes) and INPUT * (which reads). A Channel also acts as a data buffer (through which date flows) with some memory containing information on the file, such as its name, size, etc.
TOS provides you with 16 channels. To access a file, choose a free channel (one that is not being used to access another file) and associate it with the file.
To open a file use the OPEN #* instruction. The PRINT * and INPUT * instructions refer to output and input to a file through the channel number - which becomes exclusive to this file until you close it with the CLOSE #* instruction.
Closing a channel frees it, and disassociates it from the file, preventing further access to the file.
------------------------------------------------------------------------------
5.3 OPEN #*
------------------------------------------------------------------------------
The OPEN #* instruction opens a file, that is, prepares it to be accessed (read or written). Essentially, this operation consists of associating a channel with a file and establishing the access mode. In all subsequent access operations the file is referred to by the number of the channel you associated with it.
You cannot access a file that is not open. Note however, that we are referring to read and write operations using the INPUT * and PRINT * instructions.
You can access a closed file as a whole with instructions like SAVE *, LOAD * and MOVE *, but INPUT * and PRINT * are the only instructions that allow access to a specific part of a file.
The syntax of the OPEN #* instruction is
OPEN #* channel; pathname; mode; [rec-length]
The '#' is printed by the SPECTRUM as part of the OPEN keyword.
The OPEN parameters have the following meaning:
CHANNEL : Number of the channel you want to associate with the file. This channel must not be associated with another file, and must be in the range of 1 to 16. It can be a numeric expression.
PATHNAME : Pathname designating the file. Can also designate an SCP, but not a directory. Can be a string expression.
MODE : Letter (upper or lower Case) defining the access mode. There are four possibilities:
I : Input only (You can only read the file)
0 : Output only (You can only write in the file)
R : Random access (You can only read or write the file)
A : Append (You can only write in the file. New information is appended to the Previous one)
REC-LENGTH : This is an optional parameter if the mode is I, 0 or A and defines the number of bytes (characters) of each record of the file. Must be a number in the range 1 to 256. Can be a numeric expression. If this parameter is omitted, the last semicolon must not be Present.
Examples:
100 INPUT "File name?"; f$
110 INPUT "Channel number?"; n
120 DIM *f$
130 OPEN #*n;f$;i
140 REM the file is now open and ready to be read
2000 DIM *"Workfile"
2020 OPEN #*15; "Workfile";r;150
2050 REM the file WORKFILE is now ready to be read or written to with a record length of 150
The mode parameter defines the access mode (input, output, random or append). The last parameter defines the record length. If omitted, we say that the file is open, as a stream file; if present, we say that the file is open as a record file. If you specify the r mode you cannot omit this parameter.
This describes what the file structure is expected to be. If the file is open as a stream file, you can read or write a variable number of characters up to 256. If you open the file as a record file, you can only read or write a fixed number of characters the number you specified in the record-length parameter of the OPEN #* instruction.
Stream files are better suited to deal with information that has no special structure. Record films have an underlying record structure and are particularly useful when dealing with data bases, where a record holds information of a fixed length.
Stream files can only be read or written sequentially. When you perform consecutive INPUT * instructions on a stream file, you read the characters one after the other.
Record files can be read or written in a random manner, you specify - using the 'AT' statement - the number of the record you want to read with the PRINT * and INPUT * instructions,
A file is accessed using a file pointer, understanding the concept is important. In stream files the basic information unit is the character. In record files the basic information unit is the record (which can have up to 256 charaters). If you want to access a particular character in a certain record, you must read the entire record. Whichever the basic information unit is, an open file always has a pointer pointing to it. In stream files this file pointer points to the character which will be read or written next. In record files, the file pointer points to the number of the record that will be read or written next. Record files can also be accessed sequentially, record after record.
When the OPEN #* instruction is executed, the file pointer is initialised to different values, according to the mode parameter. If the file is open in input or output (stream or record files) or random (record files), the file pointer is initialised to 1, even if the file is empty.
If the file is open in the append mode, the file pointer is initialized with the file size plus 1 (stream files) or with the number of records contained in the file plus 1 (record files), corresponding to the number of the character or record that is going to be written next.
If you open a file in output only mode, all its previous contents will be destroyed. Using the append mode the data is attached to the end of the file without overwriting it.
A record file will be overwritten by specifying a record number lower than the last one on the file. The changes made to a file become effective when you close it with the CLOSE #* instruction.
You can also open and read or write SCP's, but the concepts just described vary. These are described in the next chapter devoted to SCP's.
The following you cannot do with the OPEN #* instruction:
-Specify a channel already in use,
-specify a channel outside the range 1 to 16. Or a record outside the range 1 to 256.
-specify a directory as the argument
-Specify a pathname using a template
-Specify a random access file without a record length.
-Specify the opening of a file in write mode, that is using, output, random or append modest to a file or disk which is write protected.
------------------------------------------------------------------------------
5.4 LIST *#
------------------------------------------------------------------------------
If a file or SCP is open the CAT * instruction displays an '0' under the 'S' field. To know in which channel(s) the file is open, its mode, type (stream or record), use the LIST *# instruction, which displays information on open files, and whose syntax is:
LIST *# [channel number]
The channel number is optional. If you specify it, TOS will only display information on that channel. If you omit it, TOS will display information on all open channels.
Try entering:
DIM *"TOS.SCR"
OPEN #*3;"tos.scr";i
This instruction opens the file 'TOS.SCR' in channel 3 in the stream input mode.
Now enter:
LIST *#
The fist line listed is the pathname of the file, starting at the root. Next comes a header and the corresponding information. Last line tells you how many free channels you have left. The information on the open file includes:
Ch : Channel number 1 to 16
T : Channel type: slow (s) or fast (f)
M : Mode: I, 0, R, or A (one of the four modes in which you can open a file)
Typ : File type: stream (STR) or record (REC)
Rln : Record length (the number you specified in the OPEN #* instruction. If the file type is stream, the value shown is 1)
Pointer : File pointer (this is the number of the character or record that is going to be read or written next, if the file is open as a stream or record file respectively. The first character or record is number 1)
Size : The size of a file in bytes. In input only, this value is fixed. In all other modes this value may grow according to what you write in the file.
Now enter:
DIM *"TOS.BAS" :SAVE *"SCREEN.SCR" SCREEN$
OPEN #*7;"tos.bas";r;20
OPEN #*16;"screen.scr";a
followed by;
LIST *#
This lists information an all open channels.
Please note:
1) Channel 3 is fast (T field) and 7 and 16 are slow.
2) File "TOS.BAS" is open as a record file with record length (Rln) of 20 bytes (characters) and the file pointer is initialised to 1.
3) File "SCREEN.SCR" is open as a stream in append mode, which is why the file pointer is initialised to 6918 (one plus the size, that is, the number of the character that will be written next).
Finally, 3 channels open leave 13 channels free.
If there is no channel open, the LIST *# will print:
16 channels free
No channels open
If you specify the number of a channel that is not open, TOS will generate the error message:
Channel not open
If you specify a channel number outside the 1 to 16 range, you will get the error message:
Illegal channel number
The LIST *# will still work if the channel is open to an SCP, with a few exceptions (see chapter on SCP's).
------------------------------------------------------------------------------
5.5 RANDOM ACCESS and SEQUENTIAL files
------------------------------------------------------------------------------
This section describes the use of random and sequencial access files.
Files can be used to store and retrieve information other than BASIC or machine code programs. For example, they can be used to keep a record of your bank account, your appointments or just a sequence of results from a calculation.
The new commands that allow you to use files from within a BASIC program work just like PRINT and INPUT but act on files instead of the screen or the keyboard.
To explain the use of these commands two small programs will be used. The first demonstrates the use of sequential files, and the second of random or direct access files.
Suppose You went to check it a number matches any of a sequence you have previously created and stored in a data file named 'TABLE.DAT'.
First you have to create this file. The program to do it could be something like this:
100 DIM *"TABLE.DAT"
110 OPEN #*1;"TABLE:DAT";0
We have created the file and then opened it for output (0 symbolizes output) through channel 1.
120 REM Table input routine
130 INPUT "How many do you wish?";a
140 FOR n=1 TO a
150 INPUT "Enter Number";a$
160 PRINT *#1;a$+CHR$13
170 NEXT n
180 CLOSE #*1
The main body of the program ends here closing the file. In line 160 we do not print the number, but its string representation and use a carriage return (ASCII code 13) after the number as a SEPARATOR. In a sequential file such as this, the charaters are printed one after another and items must be separated, otherwise you will not be able to read them back separately.
Several types of separators are recognised by the extended BASIC. You can use commas, tabs (CHR$6) or quotes. Quotes must be used in pairs and everything between them will be considered a string. This way you can save a string that has a separator code in it. If you want to save a string that includes quotes, then use two quotes like this: ""Hello"".
After running this program there will be a file in your disk with all the numbers you have entered.
Use the following program to see how to check whether a number belongs to this table or not:
200 LET TRAP=23729:LET SYSERR=23728
300 OPEN #*1;"TABLE.DAT";i
310 POKE TRAP,255
320 PRINT "0 ends Program"
330 INPUT "Number to check";n
340 IF n=O THEN GOTO 440
350 INPUT *#1;p$
360 IF PEEK SYSERR <>0 THEN GOTO 410
370 IF VAL (p$) <>n THEN GOTO 350
380 PRINT "Number ";n;" belongs to the table"
390 RESTORE *#1
400 GOTO 330
410 PRINT "Number ";n;" does not belong to the table"
420 GOTO 3?0
430 REM Program end
440 CLOSE #*1
450 POKE TRAP,O
460 PRINT "End of program"
Line 200 defines variables used for error trapping-see appendix E. Line 310 enables the error trapping routine. The loop in line 330 checks if the number presently entered figures in our list by checking it against all the numbers in the file. If you have already run the previous programme then enter run 2OO.
In line 350 a value is INPUT * from the file. This value is in the form of a string (p$) and is converted to a number in line 370 using VAL. All information transmitted to or from a file must be in string format.
The RESTORE in line 390 resets the file pointer so that every search starts at the beginning of the file.
The most important points concerning files and sequential access modes are;
1 - You can only use strings when reading or writing to a file.
2 - These strings have a maximum length of 256 bytes.
3 - You cannot use string arrays with more than one dimension for input.
4 - There must be 2 separator between strings in a file or you will not be able to read them back separately.
5 - There must be only one string expression in each PRINT * statement. It you want to print several items join them by a Plus '+'.
6 - In a sequential file you can only read or write items one after the other.
7 - If you open an already existing file for output its previous contents will be lost.
Another important point about files is record access.
You can write to a file as if it were an endless tape, separating the items for later reading, or you can define a fixed record length and every time you access the file the information transfer will be made in chunks of fixed length, disregarding the separator characters. For example enter:
DIM *"NAMES" (As a direct command)
100 OPEN #*1;"NAMES";0;30
110 FOR n=1 TO 20
120 INPUT "Name";n$
130 PRINT *#1;n$
140 NEXT n
150 CLOSE #*
This program will prompt for and write 20 names to a file called NAMES, each using 30 bytes. If n$ is longer than 30 bytes, only the first 30 will be written, if Shorter, the remaining bytes will be filled with blanks.
The names may be read back using this program:
200 OPEN #*1;"NAMES";I;30
210 FOR n=1 to 20
220 INPUT *#1;a$
230 PRINT a$
240 NEXT n
250 CLOSE #*
This program works without using separators, but you must know in advance the record length you are going to use. You could remove the carriage return from line 160 in the Program that generates the "TABLE.DAT" file (see above) if You introduced a fixed record length in line 110.
You must read the file using the same record length you used when you wrote it, otherwise you will read back different strings from those you wrote.
This can be useful to study the contents of a file. For example:
100 INPUT "Name of file to read";n$
110 LET x=1
120 OPEN #*1;n$;I;1
130 INPUT *#1;a$
140 PRINT x,a$;" ";CODE a$
150 LET x=x+1
160 GOTO 130
will read a file and display each character and its code, until the end of file is reached and the program stops (try it with NAMES)
The next example is an direct access files. With this type of access you can read or write to any place in the file but you must use fixed length records. This mode is useful to define records such as those in an address book where each entry has a predefined size.
The demonstration programme reads records without resetting the file pointer every time a search is made, and writes anywhere in the file without upsetting other records.
This program uses only one of the sixteen channels and the string slicing function to separate fields. Alternatively you could use several channels and allocate one to each of the fields thus avoiding the need for the string slicing function.
Please refer to the program 'ADDRESS' on your demo disk.
90 LET TRAP=23729
95 POKE TRAP,255
100 DIM *"address.dat"
110 POKE TRAP,O
115 OPEN #*1;"address.dat";r;10O
120 INPUT "1-Read,2=Write and 3=End";h$
130 IF h$="2" THEN GOTO 500
135 IF h$="3" THEN GOTO 610
140 IF h$<>"1" THEN GOTO 120
150 REM Read a record
160 INPUT "Record number";n
165 REM File size limited to 65535 records
170 IF n>65535 OR n<1 THEN GOTO 160
180 INPUT *#1;a$;AT n
190 CLS
200 PRINT AT 4,3;"Name: ";a$( TO 30)
210 PRINT AT 8,0;"Address: ";a$(31 TO 60)
220 PRINT AT 12,7;"Phone: ";a$(61 TO 75)
230 PRINT AT 16,2;"Notes: ";a$(76 TO)
Z40 INPUT "Enter to continue";h$
250 GOTO 120
500 REM Write a record
510 INPUT "Record number ";n
520 IF n>65535 OR n<1 THEN GOTO 510
530 CLS
540 DIM n$(30): DIM b$(30): DIM p$(15): DIM c$(25)
550 INPUT "Name ";n$
560 INPUT "Address ";b$
570 INPUT "Phone ";p$
590 INPUT "Notes ";c$
590 PRINT *#1;n$+b$+p$+c$;AT n
600 GOTO 120
610 CLOSE #*1: PRINT "Finished"
LINES 90, 95, 110 are used for the error trapping. It is not possible to DIM * an existing file name. The second time through the programme, an error would stop the programme, these lines prevent this. See Appendix E
LINE 115: Opens the file 'address.dat' as a random access file with a record length of 100 (256 maximum)
LINE 170: Is the system limit, normally 2 lower limit would apply
LINE 160: Read from the disk the record n (a$ will need slicing)
LINE 590: Writes the record to the disk, as a single string
LINE 610; The file must be closed. Otherwise records will not be updated.
The BASIC programme could be more sophisticated, the point here is to demonstrate the way that the TOS commands are used.
Specific records are written or read according to the number following the AT statement. Access times to specific records can be much shorter than with sequential type files since to access a record it is not necessary to read through the whole file.
Please note the following points:
1 - When a record is input from a file, the different fields can be separated with the string slicing function (TO).
2 - Care must be taken when writing to a record because if you specify a record number past the end of file the file size is increased until the record belongs to the file.
3 - The record number must be an integer between 1 and 65535.
The following is the complete syntax for the two commands:
PRINT *#n; Str-exp [;AT p]
INPUT *#n; Var [;AT p]
n : channel number (1 to 16)
Str-exp : any string or string expression resulting in a string with no more than 256 characters.
Var : any string variable or one dimensional string array
P : record number (1 to 65535). Optional when using random access files. If not defined, the next record position is used.
A last Point: everything said about sequential files is also true when using serial channels since TOS treats both in much the same way.
------------------------------------------------------------------------------
5.6 RESTORE *
------------------------------------------------------------------------------
The RESTORE * instruction, whose syntax is:
RESTORE *# channel-number
Allows you to reset the file pointer (to the value 1) bringing it back to the beginning of the file. This is especially useful in files open as streams which can only be accessed sequentially.
By using this command when the file is open in input only (i), you will start reading the beginning of the file again.
If the file is open in write only or append modes you will start overwriting it.
This instruction allows you to update only the initial characters of a stream file without destroying the rest of the file. Only in output mode does it destroy all the file contents.
Open the file in the append mode and then use the RESTORE * instruction: You can now start rewriting the file from the beginning without destroying all its contents.
The process is the same for record files, although you can avoid the use of RESTORE * by always specifying the number of the record you want, they can also be accessed sequentially.
------------------------------------------------------------------------------5.7 CLOSE *
------------------------------------------------------------------------------
When you finish accessing a file you must close it. This is done with the CLOSE #* instruction, whose syntax is:
CLOSE #*[channel-number]
(Note that the # is printed by the SPECTRUM as part of the CLOSE keyword.)
If you specify a channel number, you will only close the corresponding channel (and associated file). It you omit it, all the open channels are closed. Closing a file (or SCP) implies disassociating it from a channel.
However, if the mode is other than input only, there is more involved.
Disk files are described by a few bytes in the disk directory containing the name of the file, its size and a description of which disk blocks (1K byte each) contain data belonging to that file. Therefore, it the file was open in a write mode (output only, random or append), the CLOSE #* instruction must update these bytes to reflect the new file contents.
The way in which CLOSE #* does this depends on the mode in which the file is open. NOTE that data written into a file is NOT safe until you CLOSE that file. If something happens (e.g. a power failure) before the file is closed, you may lose information just printed to that file. So - never keep a file open in write mode longer than is necessary.
When you open a file in the output only mode the file size is initialised to zero, even if the file already has some data. This is because the output only mode overwrites the previous contents of a file. However, the old version of the file is not destroyed until you close the file.
As an example, open a file in the output mode only. To avoid destroying one of your files, copy one and work on it. Enter:
MOVE *"SCREEN.SCR" TO "NEWSCR.SCR"
open it with
OPEN #*2;"NEWSCR.SCR";0
and now enter
CAT *
The "S" field shows you that the file 'NEWSCR.SCR' is open. Note that the file 'NEWSCR.SCR', which should be 6917 bytes (being a screen), exhibits a size zero.
The 'Cur' field, which shows the currently used space in the disk, exhibits a value that is 7k bytes larger than the sum of the allocated spaces of all the files.
This is because the old version of 'NEWSCR.SCR' is still there, hidden by the system.
If you enter:
LIST *#2
you can list additional information on channel 2, open to this file.
Note this is a fast channel. The file is open as a stream in output only mode, has size 0 and the next character to be written will be the first, This information concerns the open version of the file.
You can new start writing data on the file. Try running the following program:
10 FOR n=1 TO 80
20 PRINT *#2;"a"
30 NEXT n
Now enter
CAT *
File 'NEWSCR.SCR' now has a size of 80 bytes and an allocated space of 1k. The 'Cur' field has been incremented by one due to the 1K block allocated to the open version of 'NEWSCR.SCR'. This means that the CAT * instruction follows the development of the file, allowing you to monitor its growth, as does the LIST *
instruction.
Enter
LIST *#2
Now let us simulate a power failure. Press the reset button of the disk controller. This resets the entire system. Now enter:
LIST *
The fact that there are no channels open does not mean that they have all been closed. The term used here is 'aborted', meaning that your work on the open files ('NEWSCR.SCR') is lost. To better understand this, enter:
CAT *
The file 'NEWSCR.SCR' is still there, with all its 6917 bytes - so you didn't lose the old version of the file - but you did lose the 80 bytes (1K) used in the new version of the file.
Now do it Properly. Run the program:
5 OPEN #*2;"newscr.scr";o
10 FOR n=1 TO 80
20 PRINT *#2;"a"
30 NEXT n
40 CLOSE #*2
Now enter:
CAT *
Now the file 'NEWSCR.SCR' has size 80 and the 'Cur' field is consistent with the sun of the allocated spaces of all the files of disk. Before running this program the value shown in the 'Cur' field was 6k smaller, which proves that the old version of the file (which occupied 7 Kbytes) was erased.
This was done by the CLOSE #* instruction.
The same principle applies to the other write modes (random, access and append) with information written beyond the end of the file when it was opened.
This is the case with append in stream files, and append and random access in record files, when specifying a record number greater than the last one on file. In such a case, a system reset will lose all new information. However, if you write over already existing information, this is immediately replaced and will not be lost even in a power failure. This is also true with the RESTORE * instruction when in the append mode with stream files, and append and random access with record files, if you specify an already existing record number.
In the input mode data is never lost (even if the power fails) because the file is not being updated.
If you are writing into files always check that all files are closed before turning off your system, otherwise new information written in your files may be lost.
Errors that may occur with the CLOSE #* instruction are: if you specify a channel not open or with a number outside the 1 to 16 range, TOS will print: Channel not open and Illegal channel number respectively.
Extremely unlikely, but possible, is the error message: Directory full on disk <>, which means the disk directory has no space to hold the name and additional information of the new version of the file. This will only occur if you have the maximum possible number of files (128) per side of the disk occupied.
------------------------------------------------------------------------------
5.9 FAST AND SLOW CHANNELS
------------------------------------------------------------------------------
TOS provides you with 16 channels that are divided into two types: fast and slow. Channels 1 to 4 are fast and 5 to 16 are slow.
The difference is due to memory limitations: Each fast channel has a 512 byte buffer exclusively reserved to it whereas slow channels share a common 512 byte buffer.
TOS uses these buffers to speed up access to the disks. Reading or writing a memory buffer is much faster than reading or writing the same number of bytes in the disk. So, when you read a single byte from a file, TOS reads a lot more (256) into the channel memory buffer.
Slow channels share a common buffer, and the data in that buffer belonging to a file can be destroyed by the data of another file open in another slow channel.
When writing into a slow channel, TOS writes the data in the disk (or SCP) immediately after the PRINT * instruction, because otherwise a second PRINT *# in another slow channel would overwrite that data. As a direct consequence, TOS must perform a disk access (in case of disk files) for each PRINT *# instruction (even if you only print one character), which slows down the printing process. Hence the 'slow channel' designation.
You can observe this with the following program:
Enter :
DIM *"FILE1" as a direct command
10 LET n=4
20 OPEN #*n;"file1";o
30 FOR i=1 TO 50
40 PRINT *#n;"abcd"
50 NEXT i
60 CLOSE #*n
which stores the same string in 'FILE1' 50 times. Now run the same programme with line 10 modified to make n=5 (channel 5 is slow). The execution time is much longer because TOS accesses the disk every time line 40 is executed.
In reading operations this difference in speed does not arise unless another slow channel is used between two input operations.
In this case the date in the slow channel common buffer may be destroyed forcing TOS to re-read the file.
Before moving to CHAPTER 6 lets CLOSE #* channels that may be open due to the examples of CHAPTER 5.
CLOSE #*
Closes all channels.
------------------------------------------------------------------------------
CHAPTER 6
------------------------------------------------------------------------------
6.1 Serial communication ports SCP's
------------------------------------------------------------------------------
Your Floppy Disk Controller is equipped with two RS232C Serial Communication Ports (SCP's),
These R5232C interfaces are referred to as:
"CH_A.SCP"
"CH_B.SCP "
Entering the following will demonstrate this:
CAT *":"
SCP's are a special kind of file that convey data instead of storing it. Data is transmitted or received in a serial fashion, one bit at a time. TOS uses software and hardware protocols to ensure that the transmitter only sends data when the receiver is ready.
The instructions used to exchange information with the outside world via SCP's are: SAVE *, LOAD *, MERGE *, MOVE *, PRINT * and INPUT *.
------------------------------------------------------------------------------
6.2 SCP CONFIGURATION (FORMAT *)
------------------------------------------------------------------------------
Communication between two computers (and/or peripherals) through an RS232C interface is only possible when they use matching protocol. To permit a wide range of protocols, TOS provides an instruction to set all the parameters to the required values.
The syntax of this instruction is:
FORMAT * SCP - pathname
which is distinct from the disk formatting instruction because the 'TO' and the disk name are missing. As with any instruction using a pathname, you can either start at the root (i.e. FORMAT *":CH_A.SPC") or you can start at your disk directory.
Enter.
FORMAT *"^CH_A.SCP"
The type SCP is optional, so you could enter:
FORMAT *":CH_A"
TOS prompts for the required values to be entered, but as default uses predefined setting. If you press ENTER, TOS proceeds to the next question and maintains the previous value for that parameter. If you press SPACE, TOS terminates the command and maintains the former values for the subsequent parameters. It you press a key that is neither ENTER, nor SPACE, nor any of the alternatives asked by the question, TOS repeats the question. Replies may be entered in upper or lower case.
When FORMATting a serial port, these are the questions asked:
1. Text or Bytes (T/B) ?
If the data type is text answer 'T' this will set bit 7 of every transmitted data byte to 0. If the data type is bytes, all data is transmitted without modification.
2. Auto line feed (Y/N) ?
This question appears if the data type is text. Answering yes, TOS will insert a line feed (ASCII code 0AH) after each carriage return (ASCII code 0DH).
3. XON / XOFF (Y/N) ?
Choosing this option TOS establishes a software protocol using two special control characters:
X ON (ASCII code 11H) enabling transmission and X OFF (ASCII code 13H) disabling transmission.
4. Input with wait (Y/N) ?
Answering no, all read operations to the SCP will return even it the requested data is not present, as TOS won't wait for data to in the channel buffer. This is somewhat similar to the INKEY$ function provided by the SPECTRUM. Otherwise TOS will wait for the requested data.
5. Baud rate (A-P) ?
This parameter determines the number of transmitted bits per second, the transmission speed. The correspondence between letters and baud rates is:
Letter Baud rate (bits/second)
A 50
B 75
C 110
D 134.5
E 150
F 200
G 300
H 600
I 1.200
J 1.900
K 2.400
L 3.600
M 4.800
N 7.200
O 9.600
P 19,200
6. Parity (E=Even, O=Odd, N=None) ?
This is an error detection mechanism that uses a bit to make the numbers of 1's odd (0) or even (E). The mechanism can be disabled (N).
7. Stop bits (A=1, B=1.5, C=2) ?
This is the minimal number of bits between the end of one byte and the beginning of the next.
8. Bits/char (A=5, B=6, C=7, D=8) ?
Number of bits of each data byte. Although the normal value is 8, some equipment uses less bits. Possible values are 5, 6, 7, and 8.
The factory default setting is:
1 : Bytes
2 : No auto line food
3 : No X ON / X OFF
4 : Input operation with wait
5 : 1200 baud
6 : No parity (none)
7 : 1 stop bit
8 : 8 bits per character
The new setting values defined by the FORMAT * will be destroyed when you turn your system off or press the Disk controller reset button. However, you can make these new values permanent by formatting a disk after configurating the SCP's. This will store the operating system (TOS) in the disk with the current SCP configuration.
If you don't like the names "CH_A" and "CH_B" you can change them with the LET * instruction.
Note, however, that it is the disk inserted in drive A that provides the operating system. So if you want to use your own SCP configuration - instead of the factory default system - you must use this new disk in drive A. Or run the the utility LOSYS in all existing disks (see appendix c).
You cannot configure an open SCP. If you do, you will get the error message:
<> is open
The angle brackets representing the name of the SCP in question,
------------------------------------------------------------------------------
6.3 TRANSMITTING FILES THROUGH SCP's
------------------------------------------------------------------------------
There are four instructions to exchange files: SAVE *, LOAD *, MERGE * and MOVE *
They all work as the disk files do. The SAVE * instruction allows you to transmit a program, code or data currently in memory, LOAD * and MERGE * perform the inverse operation. Note the auto run facility is also available e.g. SAVE *":CH_A" LINE 20.
MOVE * allows you to copy a disk file to an SCP (or vice-versa) or an SCP to another SCP.
The SCP's used must be configured with the data type 'bytes', since the data type 'text' gives special interpretation to some codes. TOS does not check this. These instructions deal with whole files. To transmit or receive byte by byte the PRINT * and INPUT * instructions must be used.
SCP's are interpreted by TOS as normal files with special characteristics. Thus, you can also access SCP's with PRINT * and INPUT * instructions. To do so you have to open and close the SCP's.
------------------------------------------------------------------------------
6.4 OPEN #*
------------------------------------------------------------------------------
The syntax of this instruction is:
OPEN #*channel-number;SCP-pathname;mode;record-length
Using SCP's the random access mode (r-input or output) has a special meaning, since each SCP can transmit and receive. This mode means you can transmit by writing with PRINT *# or receive by reading with INPUT *#.
As SCP's have no permanent data (SCP's send data - they do not store it) the append mode is given a special meaning. For instance, if you enter:
OPEN #*1;":ch_a";a
This means that "CH_A.SCP" will be open in the output only mode, with the data type 'text', the auto line feed and X ON / X OFF options independentely of the first four parameters of the SCP configuration settings.
In all other modes the SCP is programmed with the setting it had when you opened it.
As the append mode has this special meaning, there is no need to specify a record length. It you do TOS prints the error message:
Illegal mode/type combination
Also you cannot use the random access mode (input and output) if the X ON / X OFF Protocol option is on, because one way (transmit or receive) of the channel is needed to transmit the X ON and X OFF control characters, and it therefore cannot carry data too. If you have an SCP configurated to support an X ON / X OFF protocol and try to open it in the random access mode, TOS will generate the error message:
Illegal mode / SCP configuration
The same message is issued it you try to open an SCP and specify a record length when the SCP is configured with the data type 'text'. This is because words have a variable length. You cannot open an SCP input or random access in a slow channel because the system may need to use the slow channel common buffer to access another slow channel before it reads and stores all the bytes received by the SCP.
This is no problems with disk files because even if the bytes in the buffer are destroyed the disk file can be read back. SCP's do not have a memory and the bytes are only received once. In output only or append modes this is no problem because SCP's transmit all the information as you write it with the PRINT * instruction.
So, if you try to open an SCP in the input only or random access modes, TOS will generate the error message:
Cannot use a slow channel
Unlike disk files, you cannot open an SCP in more than one channel (even if the mode is input only) because data read from an SCP is no longer available for another read operation. This is because SCP's have no memory. If you could read an SCP from more than one channel the bytes received would be dispersed among those channels and no channel would receive the whole information.
If you try to open the same SCP in more than one channel you will got the error message:
<> is open
------------------------------------------------------------------------------
6.5 CLOSE #*
------------------------------------------------------------------------------
The CLOSE #* instruction is no different from the disk file CLOSE #* instruction except when the SCP is open in one of the write modes and with the data type 'text'.
In this case an end of file character (^Z,ASCII code, 1AH) is sent through the SCP to inform the other party that no more date will be sent through the channel.
------------------------------------------------------------------------------
6.6 LIST *#
------------------------------------------------------------------------------
This instruction lists information on open channels and has a different presentation with disk files and SCP's because the information to be displayed is different.
With SCP's the information listed includes:
Ch - Channel number (1 to 16)
T - Channel type: slow (S) or fast (F)
M - Mode: I,O,R or A
Typ - Type: stream (STR) or record (REC)
Rln - Record length : number of bytes of each record
Baud - Baud rate 50 to 19200 baud
Dat - Data type Text (TXT) or bytes (BYT)
A - Auto line feed : yes (Y) or no (N)
X - XON/XOFF protocol : yes (Y) or no (N)
W - Wait on input : yes (Y) or no (N)
------------------------------------------------------------------------------
6.7 RESTORE *
------------------------------------------------------------------------------
If the SCP is open in input only or random access mode, this instruction flushes the input buffer, erasing all bytes in the channel buffer waiting to be read.
If the SCP is open in another mode this instruction has no effect.
------------------------------------------------------------------------------
APPENDIX A - ERROR MESSAGES
------------------------------------------------------------------------------
This appendix includes the list of all the error codes and the messages which the system generates. To help you discover why the error arose a list of reasons is given below for each of the error messages.
The symbols <> are used to represent a name output by the system
------------------------------------------------------------------------------
30 ILLEGAL PATHNAME
------------------------------------------------------------------------------
-A character with ASCII code outside the range 32 to 126
-more than 64 characters (including spaces)
-no characters besides spaces or no characters at all
-spaces between two characters where neither of the characters is a separator (':', '^' or '.').
-a filename with more than 8 characters or an extension with more than 3
-a name and/or type without characters (spaces do not count)
-a file name with more than one '.'
-two colons (':') together
-an up arrow ('^') and a colon (":") together
-an up arrow preceded by a character other than an up arrow
-a template character ('+' or '?') not in the last file name, that is, a colon after a template character
------------------------------------------------------------------------------
31 NON EXISTENT PATH
------------------------------------------------------------------------------
A pathname beginning with up arrows tried to go higher than the root. Either you used more up arrows than you should or your current directory is not as low as you thought.
------------------------------------------------------------------------------
32 ILLEGAL USE OF A ROOT NAME
------------------------------------------------------------------------------
You cannot specify (1) the root or (2) a name in the root (disk name or SCP). This error can occur in the following instructions that have a pathname as their argument:
(1) All except GO TO *, GO SUB * and CAT *
(2) DIM *, ERASE * and SAVE *
------------------------------------------------------------------------------
33 <> HAS WRONG TYPE
------------------------------------------------------------------------------
(1) a file (2) a directory or (3) an SCP was specified where not allowed. This error can occur in the following instructions:
(1) GO TO *, GO SUB * and FORMAT * (SCP and disk.)
(2) OPEN #*, MOVE *, FORMAT * (SCP), LOAD * and MERGE *
(3) GO TO *, GO SUB *,ATTR * and FORMAT * (disk)
------------------------------------------------------------------------------
34 <> DOES NOT EXIST
------------------------------------------------------------------------------
You specified a pathname in which a name (not necessarily the last one) does not exist. Note that this does not mean that the name does not exist in your system: it just means that it was not found in the path specified in the pathname. This error can occur in all the instructions requiring pathnames, except DIM * and FORMAT * (disk).
------------------------------------------------------------------------------
35 <> ALREADY EXISTS
------------------------------------------------------------------------------
You tried to create a name that already exists. This error can occur in the DIM *, LET * and MOVE * instructions.
------------------------------------------------------------------------------
36 TYPES DO NOT AGREE
------------------------------------------------------------------------------
This error occurs in LET * if the type (file, directory or SCP) of the second pathname does not agree with that of the first.
LET * can only change the name, not the type.
------------------------------------------------------------------------------
37 TEMPLATE NOT ALLOWED
------------------------------------------------------------------------------
You must use a name not a template. Templates are only allowed in ERASE *, MOVE * (only in the first Pathname), CAT * and ATTR *.
------------------------------------------------------------------------------
38 NO FILES MATCHING THE TEMPLATE
------------------------------------------------------------------------------
You specified a template correctely, but there were no files (or directories or SCP's matching it). This error can occur in the ERASE *, MOVE *, CAT * and ATTR * instructions.
------------------------------------------------------------------------------
39 DIRECTORY FULL ON DISK <>
------------------------------------------------------------------------------
The system tried to create or update a file but there was no space in the disk directory. This error can occur in the DIM *, CLOSE #*, MOVE * and SAVE * instructions.
The disk directory can hold 128 entries. The disk itself uses one entry for its name. Other directories also use one entry, and files occupy one entry per each 16K in size. Therefore, a file with 7K uses one entry and a file with 50K uses 4 entries.
------------------------------------------------------------------------------
40 DISK <> FULL
------------------------------------------------------------------------------
The disk has no more space. This error may result from SAVE *, MOVE * or PRINT * instructions.
------------------------------------------------------------------------------
41 NO ROOM FOR FILE IN CHANNEL <>
------------------------------------------------------------------------------
This error occurs in the PRINT * instruction with a file open as a record file, with a record number so high that it would increase the file size to a value beyond the free space in the disk. With this error the disk maintains its free space.
------------------------------------------------------------------------------
42 <> IS WRITE PROTECTED
------------------------------------------------------------------------------
You tried to update or erase a file or directory that has been protected by the ATTR * instruction.
This error can be generated by the SAVE *, ERASE *, MOVE * and OPEN * instructions.
------------------------------------------------------------------------------
43 DISK <> IS SOFTWARE W/P
------------------------------------------------------------------------------
You cannot create, update, erase, rename or even write protect a file or directory defined in a disk that has been write protected by software with ATTR *. This error can be generated by SAVE *, OPEN #*, CLOSE *, DIM *, ERASE * LET *, MOVE *, PRINT * or ATTR *. Note that the FORMAT * (disk) does not generate this error because this instruction formats a disk, even if it software write protected.
------------------------------------------------------------------------------
44 DISK <> IS HARDWARE W/P
------------------------------------------------------------------------------
The disk is hardware write protected by the write protect tabs. The FORMAT * (disk) instruction will not format a hardware write protected disk, but generates the error: 'hardware fault on disk <>' instead.
------------------------------------------------------------------------------
45 <> HAS DIRECTORIES
------------------------------------------------------------------------------
You cannot erase a directory that contains other directories. You must erase the lower level directories first and then proceed upwards, erasing all the directories until you can finally erase the one you want. This error is generated by the ERASE * instruction.
------------------------------------------------------------------------------
46 <> HAS FILES OPEN
------------------------------------------------------------------------------
You cannot erase a directory that contains open files. You must close all files defined in the directory before you can erase it. This error is generated by the ERASE * instruction.
------------------------------------------------------------------------------
47 <> HAS FILES W/P
------------------------------------------------------------------------------
You cannot erase a directory that contains write protected files. You must unprotect them with the ATTR * instruction before you can erase the directory. This error is generated by the ERASE * instruction.
------------------------------------------------------------------------------
48 CANNOT ERASE CURRENT DIRECTORY
------------------------------------------------------------------------------
You cannot erase a directory if it is your current directory. Change it with GO TO *. This error is generated by the ERASE * instruction.
------------------------------------------------------------------------------
49 CANNOT CREATE MORE DIRECTORIES
------------------------------------------------------------------------------
You can create up to 15 directories in each side of each disk. This error is generated by the DIM * instruction if you try to create more. The structure of the directory tree does not matter.
------------------------------------------------------------------------------
50 ILLEGAL DIRECTORY SPECIFICATION
------------------------------------------------------------------------------
This error is generated by the LET * instruction if the first and second pathnames specify names (files, directories or SCP's) defined in different directories.
------------------------------------------------------------------------------
51 DIRECTORY STACK OVERFLOW
------------------------------------------------------------------------------
The directory stack has only 8 levels. This message appears if you execute a GO SUB * instruction at level 8.
------------------------------------------------------------------------------
52 CANNOT RETURN FROM LEVEL 0
------------------------------------------------------------------------------
You execute a DRAW * instruction while at level 0. Probably a DRAW * without a GO SUB *.
------------------------------------------------------------------------------
53 CHANNEL BUSY
------------------------------------------------------------------------------
This error is generated by the OPEN #* instruction it you specify the number of a channel that is already open. Change the channel number or close the other file first.
------------------------------------------------------------------------------
54 CHANNEL NOT OPEN
------------------------------------------------------------------------------
You tried to execute CLOSE *, LIST *#, PRINT *#, INPUT *# or RESTORE *# with a number corresponding to a channel that is not open.
------------------------------------------------------------------------------
55 ILLEGAL CHANNEL NUMBER
------------------------------------------------------------------------------
You specified a channel number outside the range 1 to 16 in one of the following instructions: OPEN #*, CLOSE #*, LIST *#, PRINT #*, or RESTORE *#. Possibly a variable with a wrong value.
------------------------------------------------------------------------------
56 NO CHANNELS OPEN
------------------------------------------------------------------------------
You executed a CLOSE #* without argument (close all channels) but all channels were already closed. This message also appears in the LIST *# instruction, but constitutes no error, just an information report.
------------------------------------------------------------------------------
57 NO CHANNELS FREE
------------------------------------------------------------------------------
This error message is generated by the instructions that access files as a whole, that is, SAVE *, LOAD *, MERGE * and MOVE *. The three first need one channel and MOVE * needs two. This error occurs if there are not enough free channels.
------------------------------------------------------------------------------
58 NO FAST CHANNELS FREE
------------------------------------------------------------------------------
This error can only occur when trying to copy an SCP to a file or another SCP. SCP's can only be read using fast channels. The MOVE * instruction also issues this message if channels 1 to 4 are busy.
------------------------------------------------------------------------------
59 CHANNEL TABLE OVERFLOW
------------------------------------------------------------------------------
The channel table holds information on open channels and has a capacity of 128 entries. SCP's use one entry each. Files use one entry per 16K in size (an empty file uses one entry). This error occurs if TOS tries to exceed this number of entries. Closing a channel releases space in the table. This error can be generated by SAVE *, LOAD *, MERGE *, OPEN #*, MOVE * and PRINT *
------------------------------------------------------------------------------
60 ILLEGAL MODE/TYPE COMBINATION
------------------------------------------------------------------------------
-This error expresses an incompatibility between the mode and type in the OPEN #*. It will occur in the following situations:
-(1) - opening a disk file in random access mode (r) without specifying the record length.
-(2) - opening an SCP in append mode (2) and specifying a record length.
------------------------------------------------------------------------------
61 ILLEGAL RECORD LENGTH
------------------------------------------------------------------------------
You specified a record length in the OPEN #* instruction that is outside the range 1 to 256. Any variable used in the instruction must be within this range.
------------------------------------------------------------------------------
62 CANNOT USE A SLOW CHANNEL
------------------------------------------------------------------------------
You cannot open an SCP in input or random access mode and specify a slow channel. Use a fast channel.
------------------------------------------------------------------------------
63 <> is OPEN
------------------------------------------------------------------------------
You tried to open a file or SCP, but it was already open in another channel. You can only open a disk file in more than one channel if the mode is input only. This error is generated by the OPEN #* but it can also occur in the SAVE *, LOAD *, MERGE * and MOVE * instructions which open files and SCPs to access them.
------------------------------------------------------------------------------
64 <> CHANGED WITH FILES OPEN
------------------------------------------------------------------------------
You replaced a disk but the old one had at least one file open. You must replace the old disk to close the files(s) before using a new disk.
------------------------------------------------------------------------------
65 CANNOT FORMAT WITH FILES OPEN
------------------------------------------------------------------------------
This error occurs in the FORMAT * (disk) instruction if you have at least one file or SCP open. You must close all files before formatting a disk.
------------------------------------------------------------------------------
66 ILLEGAL DRIVE NAME
------------------------------------------------------------------------------
This error occurs in the FORMAT * (disk) instruction if you specify anything than A, B, C or D (upper or lower case) in the first string. These are the legal drive names, spaces are ignored.
------------------------------------------------------------------------------
67 ILLEGAL DISK NAME
------------------------------------------------------------------------------
This error occurs in FORMAT * (disk) instruction if you do not specify a single, legal name in the second string. You must specify a disk name, that is, a directory name not a pathname.
------------------------------------------------------------------------------
68 BUFFER FULL
------------------------------------------------------------------------------
This error occurs in the INPUT *# instruction when reading fromn an SCP, if the channel buffer becomes full - data incoming rate greater than system throughput - and you have no protocol to stop the transmiter. Configure the SCP to appropriate protocol.
------------------------------------------------------------------------------
69 SCP I/O ERROR
------------------------------------------------------------------------------
A transmission error was detected when reading from an SCP.
------------------------------------------------------------------------------
70 ILLEGAL OPERATION ON READ FILE
------------------------------------------------------------------------------
You executed a PRINT *# instruction with a channel number corresponding to a file or SCP open in input only.
------------------------------------------------------------------------------
71 ILLEGAL OPERATION ON WRITE FILE
------------------------------------------------------------------------------
You executed a INPUT *# instruction with a channel number corresponding to a file or SCP open in output only or append.
------------------------------------------------------------------------------
72 READ PAST END OF FILE
------------------------------------------------------------------------------
You executed an INPUT *# instruction in a channel corresponding to a file whose pointer was at the end of the file. No data is read.
------------------------------------------------------------------------------
73 HARDWARE FAULT ON DISK <>
------------------------------------------------------------------------------
This message can be generated by any instruction that reads or writes from or to the disk. A hardware fault may be detected, either from the disk itself or the drive. A likely cause is that there is no disk in the drive, and note the system does not work unless there is a disk in drive A.
------------------------------------------------------------------------------
74 DISK CORRUPTED
------------------------------------------------------------------------------
This message appears if either:
(1) - The disk is partially destroyed through magnetic fields, heat, etc.
(2) - Your operating system loaded in memory is corrupted, due to noise, caused by electrical interference.
(3) - You have replaced the disk in drive A, and the new disk has a diferent version of the operating system TOS.
You shoud reset your system. If the message persists, then the disk has becoma corrupted. In most cases you should be able to recover all or most if your files from the faulty disk. by copying them onto a good disk.
------------------------------------------------------------------------------
75 ILLEGAL DATA TYPE
------------------------------------------------------------------------------
This error occurs in the LOAD * instruction if you specify an option (CODE, SCREEN$, DATA or name) that is not the same or compatible with the option of the SAVE * that created the file. This error is also generatedif you try to load a file not generated by SAVE * or MERGE * - a file that does not contain a BASIC programme.
------------------------------------------------------------------------------
APPENDIX 6 - TOS summary
------------------------------------------------------------------------------
This appendix presents a brief description of each one of the extended BASIC instructions provided by TOS in alphabetical order.
For reference,
The arguments between square brackets are optional '[]'.
<> are used to represent a disk name/number/file/ or pathname output by the system.
------------------------------------------------------------------------------
ATTR *
------------------------------------------------------------------------------
Syntax: ATTR * pathname P or U or I or V
The P or U Protects or Unprotects a file respectively whereas I hides a file from the CAT * display and V unveils it.
Protected files are recognized by the appearance of a P under the rightmost field of the disk directory. If the file is unprotected, this field appears blank. Obviously neither 'V' nor 'I' will ever be displayed under the status field.
The pathname can be a template, so you can protect (or unprotect), hide (or unveil)more than one file with the same command.
A protected file cannot be erased or written to. If you protect a disk, then you cannot write to that disk. Note that the FORMAT * instruction can destroy a protected disk.
------------------------------------------------------------------------------
CAT *
------------------------------------------------------------------------------
Syntax: CAT * [pathname]
Without the pathname, this instruction displays information on all the files defined in the current directory. It the argument is specified, only the information concerning the files designated by the pathname (which can be a template) is listed.
This information consists at:
(1) General Data
1 - Pathname of the directory where the files are defined
2 - Its level
3 - The name of the drive where it is physically defined
4 - The disk capacity, the currently used space and the remaining space, all in K bytes.
(2) File Specific Data
1 - Name (including type)
2 - Size in bytes
3 - Real size in K bytes (the space actually used)
4 - File status (open or closed)
5 - File protection state (write protected or unprotected)
As a special case, executing this instruction in the root shows the physical resources of your system, that is, the disk currently used and the SCP's.
------------------------------------------------------------------------------
CLOSE #*
------------------------------------------------------------------------------
Syntax: CLOSE #* expression
This instruction closes the open file linked to the channel number given by the expression.
The channel is disassociated from the file and becomes free.
If the file was open for input only, it suffers no modification. If the file was open for output only, or for random access (input/output) or append, this instruction updates the file with the modifications made to the file. If the system is initialized (by pressing the reset button or switching it off and on) the previous version of the file (prior to the OPEN #* instruction) will remain unchanged. The modifications made will only be transferred to the disk after the CLOSE #* instruction.
------------------------------------------------------------------------------
MOVE *
------------------------------------------------------------------------------
Syntax: MOVE * source-pathname TO destination-pathname
This instruction copies a file or SCP to another file or SCP. The source is not destroyed nor modified. The following combinations are allowed :1 Copying a file to a file makes a file duplicate allowing you to produce backup copies. 2. Copying an SCP to a file 3. Copying a file to an SCP. 4. Copying an SCP to an SCP.
The source-pathname can be a template, allowing you to copy several files with a single command, but in this case (and only in this case) the destination pathname must be a directory. All the files matching the template will be transferred to this directory, unless an error occurs.
TOS prints the names of the files (or error messages) as they are being copied.
SCP's cannot be used if you specify a template.
------------------------------------------------------------------------------
DIM *
------------------------------------------------------------------------------
Syntax: DIM * pathname
This instruction creates a file or a directory specified by the pathname. If you want to create a directory, you must specify a name with the type "DIR". Without it, TOS will create a file.
Files are created with size 0 and newly created directories are empty. SCP's cannot be created.
------------------------------------------------------------------------------
ERASE *
------------------------------------------------------------------------------
Syntax: ERASE * pathname [N]
ERASE * erases files, that is, destroys them and removes their names from the directory where they are defined.
The pathname can be a template, so you can erase more than one file with a single command.
This instruction will generate an error if you try to erase a file or directory that is write protected or belongs to a protected disk.
TOS asks for a confirmation of erasure with the Question:
Erase <> (Y/N)? unless an 'n' is specified in the initial command
------------------------------------------------------------------------------
FORMAT * (disk)
------------------------------------------------------------------------------
Syntax: FORMAT * drive-name TO disk-name
The FORMAT * instruction formats the disk currently inserted in the drive specified. Note that you must specify the name of the drive (A, B, C or D), not the pathname of the disk.
CAUTION: This instruction destroys all the files contained in the disk. The software protection provided by ATTR * is not effective. The only way to protect a disk against formatting is to protect it by hardware, using the disk's protection tabs.
Since this is a dangerous instruction (even more so than ERASE *), TOS checks your request before formatting by printing:
Format disk in drive <> (Y/N)?
Typing N will abort the command
If you specified drive A, TOS will print an additional message:
Change diskette and press ENTER
and waits for you to press the ENTER key before proceeding.
This allows you to format disks (without destroying the disk you are using) even if you have only one drive (which is necessarily drive A).
------------------------------------------------------------------------------
FORMAT * (SCP)
------------------------------------------------------------------------------
Syntax: FORMAT * SCP-pathname
If the string expression is a pathname designating a SCP, you can change the configuration of that SCP. TOS prints the following questions:
Text or bytes (T / B)?
Auto line feed (Y / N)?
Software Protocol (Y / N)?
Input with wait (Y / N)?
Baud rate (A - P)?
Parity (N=none, E=even, O=odd)?
Stop bits (A=1, B=1.5, C=2)?
Bits/char (A=5, B=6, C=7, D=8)?
In each case, you must type one of the letters shown above. You can hit ENTER if you want to proceed to the next parameter without changing the value of the current one, or SPACE if you don't want to change any of the subsequent parameters.
------------------------------------------------------------------------------
GO SUB *
------------------------------------------------------------------------------
Syntax: GO SUB * [pathname] or GO SUB *"drivename"d
The GO SUB * instruction saves the current directory in a special stack, known as the 'directory stack'.
If the pathname is specified, then TOS changes the current directory to the one designated by the pathname.
This instruction is used in conjunction with DRAW * as an easy means of returning to the original directory - even without you knowing which this is. Several GO SUB * instructions can be nested. The CAT * instruction shows the current level of GO SUB * nesting.
It you use the 'd' Parameter you must specify the drive name (A,B,C,D) and not the pathname. Hence you can move to another drive without knowing the disk name. Note that your directory level will be incremented as the stack directory is updated.
------------------------------------------------------------------------------
GOTO *
------------------------------------------------------------------------------
Syntax: GO TO * pathname or GO TO *"drivename"d
This instruction changes the current directory to the one designated by pathname. It is similar to GO SUB *, except it does not save the current directory in the directory stack.
Similarly to GO SUB * the "d" option is available. Except that once more the directory stack is not used.
------------------------------------------------------------------------------
INPUT *
------------------------------------------------------------------------------
Syntax: INPUT *#n; VAR$ [;AT p]
Reads a character(s) or a group of characters (i.e. a record) from a file or SCP via a channel.
n-specifies a channel (From 1 to 16)
VAR$-Any string variable or one dimension string array.
P-Record number (1 to 65535). Used to point to next record to be accessed in the random access mode. If ommited the next record is used.
------------------------------------------------------------------------------
LIST *
------------------------------------------------------------------------------
Syntax: LIST *
The LIST * instruction lists information on the current directory and an all directories stored in the stack.
This information includes:
1 : The pathname of the current directory
2 : Its level
3 : The drive where its disk is inserted
This information is partially displayed in the first two lines of the listing produced by CAT *.
------------------------------------------------------------------------------
LIST *#
------------------------------------------------------------------------------
Syntax: LIST *# [channel number]
If the channel number (Can be a numerical expression) is given, this instruction lists information of the corresponding channel.
If the channel is not open, an error message is generated.
If the expression is omitted, this instruction lists information on all open channels.
This information includes:
For the channel(s) open to a file
-Channel number
-Channel type (fast or slow)
-Mode: i - input (read only)
a - output (write only)
r - random access (read/write)
a - append (write at the end of the file)
-Type (record or stream)
-Record length (1 if stream)
-Current record (file pointer position)
-Size (file size in bytes)
Channel open to an SCP
-Channel number
-Mode: i - input (receive only)
o - output (transmit only)
r - full-duplex (transmit/receive)
a - output of text with auto line feed and software protocol
-Type (record or stream)
-Record length (1 if stream)
-baud rate (50 to 19200 baud)
-Data type (text or bytes)
-Auto line-feed - yes (Y) or no (N)
-XON/XOFF Protocol - yes (Y) or no (N)
This instruction also prints the number of free channels.
------------------------------------------------------------------------------
LOAD *
------------------------------------------------------------------------------
Syntax: LOAD * pathname load-option
The LOAD * instruction is very similar to its equivalent in the SPECTRUM's BASIC. The load options are the same.
The Pathname can represent an SCP, allowing you to receive BASIC programs (or code) directly from another computer.
------------------------------------------------------------------------------
MERGE *
------------------------------------------------------------------------------
Syntax: MERGE * Pathname
This instruction is similar to its equivalent of the SPECTRUM BASIC language and merges a disk BASIC program to a program already existing in the memory of the SPECTRUM
------------------------------------------------------------------------------
LET *
------------------------------------------------------------------------------
Syntax: LET * old-pathname TO new-Pathname
This instruction renames a file, directory or SCP. Both pathnames must designate the same directory, This renaming operation does not affect the protection attribute.
------------------------------------------------------------------------------
OPEN #*
------------------------------------------------------------------------------
Syntax: OPEN #* expression 1;pathname;mode[expression 2]
This instruction opens a file or SCP and associates a channel with it, allowing you to access it through the instructions PRINT * and INPUT *.
expression 1 - channel number
pathname - pathname of the file or SCP
mode - i - input (read only)
o - output (write only)
r - random access (read/write)
a - append
expression 2 - record length
------------------------------------------------------------------------------
PRINT *
------------------------------------------------------------------------------
Syntax: PRINT *#n;STR$; [;AT P]
Writes characters or groups of characters (i.e. records) to a file or SCP via a channel.
n-Specifies channel number (1 to 16)
STR$-Any string or string expression with no more than 256 characters.
P-Record number (1 to 65535) used to point to next record to be accessed in the random access mode. Can be ommited in which case the next record will be used.
------------------------------------------------------------------------------
DRAW *
------------------------------------------------------------------------------
Syntax: DRAW *
This instruction is used in conjuntion with GO SUB * to retrieve directory information from the directory stack, and thus return to the directory that was current when the last GO SUB * instruction was executed.
The directory level is decremented by one. An error occurs if you try to execute this instruction in level 0.
------------------------------------------------------------------------------
SAVE *
------------------------------------------------------------------------------
Syntax: SAVE * pathname save-option [n]
The SAVE * instruction is very similar to its equivalent in the SPECTRUM's BASIC. The save-options are the same.
When the optional [n] parameter is given TOS will overwrite an existing file with the same filename without the usual prompting:
<> already exists
Supersede (Y/N) ?
The pathname can represent an SCP, allowing you to transmit BASIC Programs (or code) directly to another computer.
------------------------------------------------------------------------------
APPENDIX C - UTILITY PROGRAMMES
------------------------------------------------------------------------------
The demonstration disk contains a number of utility programmes to perform certain useful operations. This appendix will explain the use of these programmes. They may be found under the directory 'UTIL'.
The programmes contained are BACKUP, DUMP, LPRINT and LOSYS.
C.1 BACKUP
This programme will copy an entire disk, sector by sector, copying all the contents. This allows the creation of backup copies, and will operate by copying the disk in drive A to any of the other drives. It is Possible to copy to drive A, in which case the prompt will appear to 'change disks now'. It is necessary to shuffle between the master and the target disk until the copy is complete. Using any other drive the copy will proceed without stopping.
C.2 LOSYS
This utility allows the updating of the operating system (TOS) without the loss of data in your disk. Each side of the disk has an operating system written to it, and this utility will COPY across your programmes onto a new disk with the now operating system resident.
To run the programme: LOAD *"LOSYS"
Several options are offered in such the same way as the backup programme, responding to these options, you can work with drive A only or any one of the other three drives. This utility can be used after FORMAT *(scp) to change default setting on existing disks.
C.3 DUMP
This will allow the chosen file to be dumped onto the screen, giving, the hexadecimal bytes, for each address, and the ASCII equivalent. Where the ASCII character cannot be printed it is displayed as a . (dot). The programme will prompt you for the name of the file you want to dump in this way.
To run the Programme: LOAD *"DUMP"
C.4 LPRINT
This programme will activate your printer connected to the serial channel A to work with the commands of SPECTRUM BASIC to print text and list a programme: LPRINT and LLIST.
The programme does not use any of the main RAM of the SPECTRUM, but uses the print buffer. Every time a NEW command is made this programme will be destroyed. To use the programme it must be first loaded, then run and then line 9, which is the only BASIC line of the programme, should be erased. The programme should be entered before the main programme you want to use, however it can be MERGED to the existing programme, provided no line 9 exists. There is a STOP command at the end of line 9 to allow a merge followed by a GO TO 9. The GO TO 9 will activate the printing routine by loading the machine code required. Once the code is in line 9 is no longer required and should be deleted. The STOP command will stop entry into the main programme and allow you to break out and delete the line 9.
------------------------------------------------------------------------------
APPENDIX D - RS232C LINK-UPS
------------------------------------------------------------------------------
D.1 PIN OUT OF PLUG
The RS232C sockets are wired as follows:
+++++++++++++++++++++++++++++
+ 1 2 3 4 5 +
+ +
+ 6 7 8 9 +
+++++++++++++++++++++++
1 - N/C (not connected)
2 - TX data (transmit data)
3 - RX data (receive data)
4 - CTS (clear to send)
5 - DTR (data terminal ready)
6 - N/C
7 - Ground (signal ground)
8 - N/C
9 - +12v (Pull-up)
D.2 MAKING a standard 25 pin D-type cable to connect a Printer (available from your dealer)
FDD SYSTEM---- TO ------- RS232C peripheral connections on
9 Pin D-type 25 Pin D-type
2 ------------------- 3 Rx Data
3 ------------------- 2 Tx Data
4 ------------------- 5 CTS
5 ------------------- 20 DTR
7 ------------------- 7 Signal Gnd.
9 ------------------- 6 DSR (data set ready)
NOTE:You will need to check, your printer configuration (protocol), and match it with that of the FDD SYSTEM. You can use the default protocol (see chapter 6), and configure your peripheral to that or you can reconfigure the RS232C port's current setting by using the FORMAT *"CH_A" instruction.
The most likely need will be to reconfigure the baud rate to match the peripheral.
D.3 PRINTING CHARACTERS
There is a utility programme named 'type' which you will be able to use with your printer, making it echo the output from the keyboard like a type writer. This is under the directory named 'UTIL' on your demo disk.
Before loading the program connect a printer equipped with an RS232C interface to channel A of the controller.
D.4 USING LPRINT and LLIST
You will need the utility programme 'lprint' see appendix C
These can also pass control codes for enlarged Print etc.:
10 OPEN #*1."CH_A";a
20 PRINT *#1;CHR$(27)+'E'
30 CLOSE #*1
D.5 COMMUNICATING : FDD SYSTEM to another SYSTEM
Controller to Controller connection will use a standard TIMEX 9 Pin D type cable, to connect two FDD SYSTEMS. For any other system using an RS232C interface, follow the pin out table above, making the connections as shown. The receive programme would need to be written to suit that system.
To send characters between two systems connect the cable to both channels A of each system and load RSTRANS (under directory UTIL) into the transmitting computer. The programme listing is as follows:
Programme: RSTRANS
10 OPEN #*1;":ch_a";o
20 IF INKEY$<>"" THEN GO TO 20
30 IF INKEY$="" THEN GO TO 30
45 PRINT INKEY$;
50 PRINT *#1;INKEY$
60 GO TO 20
The receiver should load RSRECEIV (under the directory UTIL). Listing as follows:
Programme: RSRECEIV
10 OPEN #*1;"CH_A";i;1
20 INPUT *#1;A$;
30 PRINT A$;
40 GO TO 20
The receiver should start running the program before the transmitter.
You will find it easy to send programs from one computer to another. Simply load the program you want in the transmitting computer and then type:
SAVE *":CH_A" or( SAVE *":CH_B")
Note the use of CH_A or CH_B depends on the Port connections used. In the rest of these examples CH_A will be used for clarity.
The receiver should type:
LOAD *":CH_A"
All the save and load options are available (see section 3.6)
Using the MOVE * instruction it is possible to send a disk file from one computer to another using the RS232C (SCP's), linked up.
Example:
sender:
MOVE *"File name" TO ":CH_A"
receiver:
MOVE *":CH_A" TO "file name"
As before the receiver needs to be active first.
------------------------------------------------------------------------------
APPENDIX E - Error trapping
------------------------------------------------------------------------------
The extended BASIC instructions of TOS dealing with the disk drives issue an error report, where there is one. If these instructions are used within a programme, there is no way of knowing if they can be executed. For example suppose a sequential file is being accessed and it is not known where it will end. Any further data output from the file will generate an error stopping the programme. There are times that this type of error needs to be 'trapped', perhaps warning the user that this has happened, but not having the programme stop.
The method of carrying out this error trapping in TOS is using two of the unused systems variables of the SPECTRUM, which are referred to as SYSERR, and TRAP. When the SPECTRUM is turned on it writes 0 in TRAP and never uses it again. Poking another value into that location will activate the error trapping mechanism whereby TOS will write an error number into SYSERR, when one occurs, and a zero when there is not an error.
Testing for the error number and the error condition is the way that error trapping can be performed. The following example should explain the method more clearly:
50 LET TRAP=23729 :LET SYSERR=23728
100 OPEN #*1;1;"Filename";I
110 POKE TRAP,255
120 INPUT *#1;A$
130 IF PEEK SYSERR<>O THEN GO TO 500
140 PRINT A$
150 GO TO 120
500 PRINT "Reached end of file'
510 CLOSE #*1
Use any 'Filename' that exists under your current directory.
Line 110 error trapping is activated.
Line 130 the error number will appear in SYSERR, or a 0 if no there is not an error. The error numbers are those that appear in APPENDIX A.
Making use of these errors can be achieved as follows:
500 IF PEEK SYSERR<>72 THEN PRINT "System error number":PRINT PEEK SYSERR:STOP
510 PRINT "Reached end of file"
520 CLOSE #*1
Note error 72 means an attempt to read past the end of a file, any other error will cause the programme to STOP.
To disable the error trapping routine remember to POKE 23729,0
------------------------------------------------------------------------------
APPENDIX F - MACHINE CODE TIPS
------------------------------------------------------------------------------
The extended BASIC functions of TOS may be used in machine code programmes, but to do so calls must be made to the external ROM, that TOS use. The first stage is to understand the ROM swapping mechanism that is used. All the new commands are in an external ROM that uses the same address range of the standard BASIC ROM. To access that ROM it must be selected by jumping to address 0008H. After doing this the external ROM is enabled and the routines can be used. To avoid crashing the system and not losing control of your programme, it is suggested that you use the following code to switch ROM's:
PAGEIN PUSH IY ;the ROM uses IY to detect a user call
LD IY,0 ;flag user call
CALL 8 ;paging mechanism activated
POP IY ;restore IY
NOTES:
1 - After executing PAGEIN the external ROM disables interrupts.
2 - You can not use BASIC ROM routines using CBAS. CBAS is explained later
3 - You have access to 1Kbyte of RAM from 2000H to 23FFH that is used by the system to store variables and buffers. It is free from 2156H to 23FFH.
After using the external ROM you can reselect the BASIC ROM by calling 0603H or 0604H, the latter does not reenable the interrupts.
In the external ROM there is a routine to call routines in the BASIC ROM with the external ROM selected, that takes care of all switching. It is called with the address of the BASIC ROM in the next two bytes. For example:
CBAS EQU 061DH ;the spcial calling routine
CLS EQU OD6BH ;the SPECTRUM routine
CALL CBAS
DEFW CLS ;the calling address low byte first
There is a jump table starting at 0605H with some of the most useful routines in the externa1 ROM to the machine code programmer. The following is a list of the routines and the calling addresses:
0605H JP PUTDAT
Purpose :transfer a data block to the disk system
Registers used:none
INPUT :data to transfer in bufdat (2000H to 20FFH)
A - number of bytes to send
OUTPUT :none
Comment :can be aborted with break
0608H JP PUTCOM
Purpose :send command to the disk system
Registers used:none
INPUT :AF,PC, DE, HL, IX, IY
OUTPUT :none
Comment :all registers are sent to the disk system.
Can be aborted with break
060BH JP GETBLOCK
Purpose :get data or command from the disk system
INPUT :none
OUTPUT :data - carry reset and data in bufdat
command - carry set and all the registers
changed. Error code in 2100H and
error message in 21ODH to 211DH
Comment :can be aborted with break
060EH JP SENDBL
Purpose :send a package to the disk
Registers used:none
INPUT :HL - buffer pointer
(tvp), (len) - type and length of data to send
OUTPUT :zero if ok.
0611H JP GETBL
Purpose :get a package from the disk
Registers used:none
INPUT :none
OUTPUT :data in bufdat or bufcom
zero it op.
(tvp), (Ion) - type and length of data received
0614H JP RDBLOC
Purpose :tread up to 256 bytes from file
Registers used:BC, HL
INPUT :(chan) - channel number
DE : number of bytes to read
OUTPUT :zero if ok
HL points to bufdat
BC number of bytes read
0617H JP RDMEM
Purpose :read a file to memory
Registers used:A
INPUT :(prolen) - number of bytes to read
(prostr) - loading address
(chan) - channel to use
OUTPUT :zero if ok
Comment :Prolen and Prostr are two byte variables
061AH JP WRTMEM
Purpose :write memory to a file
Registers used:A
INPUT :(prolen) - number of bytes to read
(prostr) - loading address
(chan) - channel to use
OUTPUT :zero if ok
061DH JP CBAS
Purpose :Call a BASIC ROM subroutine
INPUT :address to call
Comment :all registers are preserved during the ROM switching
0620H JP SAVEP
Purpose :save code or a Program to a file
Registers used:none
INPUT :Pathname in bufdat (must end with CHR$(0))
A' - len of Pathname
BC - len of code to save
DE - code start
HL - line number it there is one
OUTPUT :zero if ok
To study the extended BASIC ROM you can use this programme:
COPY PUSH IY
LD IY,0
CALL 0008H
POP IY ;the Paging routing
LD BC,1000H ;the ROM only has 4Kbytes
LD HL,OOOOH
LD HL,DEST ;Place in, memory where code to be put
LDIR
CALL 0603H ;select the BASIC ROM
RET ;return
To send a command to the disk system you must place the command in 2100H set the Z80 registers with correct parameters and call PUTCOM. The disk tries to execute the command and sends back the result and error report (0 if 0,K). To get the result you can use GETBLOCK which returns with the carry set if the disk. sent a command or reset if it was data.
Montagem e impressão:
GRÁFICA P. CACILHAS, LDA.
ALMADA - PORTUGAL