THE ECONET SYSTEM USER GUIDE

Copyright ACORN COMPUTERS LTD 1982 29 November 1982 403,100 Issue 1 Obligatory safety instructions for inclusion in the Econet documentation to cover; the BBC Microcomputer with a three core moulded plug, the System 5 with a three core conventional plug and a clock/terminator with a two core plug, should read as follows:

WARNING: Systems 2, 3, 4 and 5 and the BBC Microcomputer must be earthed.

IMPORTANT: The wires in the mains lead for the System 5 computer and the BBC Microcomputer are coloured in accordance with the following code: Green and Yellow - Earth

Blue - Neutral

Brown - Live As the colours of the wires in the mains lead of this apparatus may not correspond with the coloured markings identifying the terminals in your plug, proceed as follows: The wire which is coloured green and yellow must be connected to the terminal in the plug which is marked by the letter E or by the safety earth symbol or coloured green or green and yellow. The wire which is coloured blue must be connected to the terminal which is marked with the letter N or coloured black. The wire which is coloured brown must be connected to the terminal which is marked with the letter L or coloured red. In the case of apparatus supplied with a moulded plug, please note the following:

If the socket outlet available is not suitable for the plug supplied, the plug should be cut off and the appropriate plug fitted and wired as previously noted. The moulded plug which was cut off should be disposed of as it would be a potential shock hazard if it were to be plugged in with the cut off end of the mains cord exposed. The moulded plug must be used with the fuse and the fuse carrier firmly in place. The fuse carrier is of the same basic colour as the coloured insert in the base of the plug. Different manufacturers plugs and fuse carriers are not interchangeable. In the event of loss of the fuse carrier, the moulded plug MUST NOT be used. Either replace the moulded plug with another conventional plug wired as previously described, or obtain a replacement fuse carrier from an authorised Acorn or BBC Microcomputer dealer.

not necessarily the same shade of that colour.

iii IMPORTANT:IntroductionThe wires in the mains lead for the mains adaptor for 1 the Acorn Atom or the Econet Clock or the Econet Termination accessories are coloured in accordance with the following code: Blue - Neutral

Brown - Live

As the colours of the wires may not correspond with the coloured markings identifying the terminals in your plug, proceed as follows: The wire which is coloured Blue must be connected to the terminal which is marked with the letter N or coloured black. The wire which is coloured Brown must be connected to the terminal which is marked with the letter L or coloured red. IMPORTANT: In the event of the fuse blowing, it should be replaced after clearing any fault, with a 3 Amp fuse that is ASTA approved to BS1362.

C.B. Turner 3.12.82

iii 1 Getting going 2 1.1 Initialising the ECONET software 1.1.1 -On the BBC Microcomputer 1.1.2 -On the Atom 1.1.3 -On the Acorn Systems 3, 4, 5 1.1.4 The No Clock message 1.1.5 What next?

2 The file server 7 2.1 What is the file server? 2.1.1 Purpose of this chapter 2.1.2 Not starting the file server! 2.2 Simple file server commands 2.2.1 A single directory 2.2.2 Commands 2.2.3 Identifying yourself 2.2.4 SAVE 2.2.5 SAVE 2.2.6 LOAD 2.2.7 LOAD 2.2.8 Listing the directory - CAT 2.2.9 File information - INFO 2.2.10 EX/INF 2.2.11 DELETE 2.2.12 RENAME 2.2.13 File access - ACCESS 2.2.14 A note on file titles 2.2.15 Multiple file servers 2.2.16 Monitor messages 2.2.17 Summary 2.3 Creating and using a hierarchy of directories 2.3.1 Directories within directories 2.3.2 Creating directories 2.3.3 Filenames 2.3.4 Selecting directories 2.3.5 The ROOT directory and USERS ROOT directory 2.3.6 Selecting discs 2.3.7 Deleting directories 2.4 Owner and public access 2.4.1 Whats the difference? 2.4.2 Becoming the owner 2.5 Passwords 2.5.1 How they are used 2.5.2 Setting the password - PASS 2.5.3 The password file 2.6 User commands and libraries 2.6.1 Commands 2.6.2 Libraries 2.6.3 RUN and / 2.7 EXEC and SPOOL 2.7.1 EXEC 2.7.2 SPOOL 2.8 Auto-start facilities 2.8.1 SettingIntroduction option 1 2.8.2 Auto-start when logging on 2.8.3 Auto-start when resetting the machine 2.9 Utility programs 2.9.1 Bow to use them 2.9.2 INF 2.9.3 DISCS 2.9.4 USERS 2.9.5 Network utilities 2.9.6 PS 2.10 Random access 2.10.1 What is random access? 2.10.2 Channels - Opening and closing files 2.10.3 Random access in BASIC 2.10.4 Using the pointer 2.10.5 Interlocks 3 Using the File Server from Assembler 34

3.1 OSFIND 3.2 OSFILE 3.3 OSARGS 3.4 OSBGBP 3.5 OSBGET 3.6 OSBPUT

4 The printer server and printing 4O

4.1 What is the printer server? 4.1.1 Using a BBC Microcomputer printer server 4.1.2 Using an ATOM printer server 4.2 Printing from a station 4.3 Several printer servers

5 Communicating with other User Stations 42 5.1 Introduction 5.2 VIEW 5.3 REMOTE 5.4 ESCAPE and BREAK in REMOTE 5.4.1 On BBC Microcomputers 5.4.2 On ATOMs and Systems 5.5 ROFF 5.6 NOTIFY 5.7 Protection 5.7.1 PROT 5.7.2 UNPROT

6 Errors 47

6.1 Errors on the BBC Microcomputer 6.1.1 Error messages 6.1.2 OSWORD call to read error numbers 6.1.3 Line jammed 6.1.4 Net error 6.1.5 No clock 6.1.6 Bad TXCB 6.2 Errors on the ATOM and Systems 6.2.1 Error messages 6.3 Errors common to all machines 6.3.1 NOT LISTENING 6.3.2 NO REPLY 6.3.3 Channel 6.4 List of Errors

7 Supervising the network 51

7.1 General principles 7.2 Hardware requirements 7.2.1 A useful file server configuration 7.3 Discs provided 7.3.1 File server and DOS discs not compatible 7.3.2 The NETWORK UTILITIES DISC 7.3.3 The FILE SERVER MASTER DISC 7.3.4 Disc care and handling 7.4 Starting the file server program 7.4.1 Basic steps 7.4.2 Routine starting procedure 7.4.3 File Server Monitor 7.5 Initialising file server discs 7.5.1 Why necessary? 7.5.2 Formatting the disc 7.5.3 Initialising the disc maps 7.5.4 Creating the ROOT and PASSWORD file 7.6 Managing the password file 7.6.1 Forgotten passwords 7.7 Privileged users - setting privilege 7.7.1 The user SYST 7.7.2 Creating and deleting users 7.8 Changing discs 7.9 Copying from DOS discs 7.10 ARCHIVING! - Data security 7.10.1 Backup routines 7.10.2 Copying on the BBC Microcomputer file server 7.10.3 Copying on the system file server 8 Installing an ECONET network 64

8.1 Items required 8.1.1 Terminators 8.1.2 Clock 8.1.3 Cable 8.1.4 Sockets 8.1.5 Suppliers 8.2 Installing a network 8.3 Setting up the network 8.4 Fault diagnosis

9 Selecting a filing system 73

vii 9.1 On the BBC Microcomputer 9.2 On Systems 9.3 On the ATOM

10 Econet primitives 74

10.1 Introduction 10.2 TRANSMIT 10.2.1 Purpose 10.2.2 The TRANSMIT control block 10.2.3 Return from TRANSMIT 10.3 RECEIVING messages 10.3.1 Introduction 10.3.2 The RECEIVE CONTROL BLOCK 10.3.3 The Receive Control Block after reception 10.4 Broadcast 10.5 Immediate operations 10.5.1 Introduction 10.5.2 PEEK 10.5.3 POKE 10.5.4 Remote subroutine JMP 10.5.5 Remote procedure call 10.5.6 Machine type (Local PEEK) 10.5.7 HALT 10.5.8 CONTINUE 10.6 Protection

11 The BBC Microcomputer operating system interface 89

11.1 Introduction 11.2 TRANSMIT 11.2.1 Calling TRANSMIT 11.2.2 Polling the TRANSMIT block 11.3 RECEIVE 11.3.1 Opening a control block 11.3.2 Polling a receive block 11.3.3 Reading a receive block 11.3.4 Deleting a receive block 11.4 Immediate operations 11.5 Remote Subroutine Jump 11.6 Remote procedure call 11.6.1 Operating system procedure call 11.7 Protection 11.8 Other OSWORD calls 11.8.1 Reading and Setting State Information 11.8.2 File Server/Remote Machine Call 11.9 Other OSBYTE calls 11.9.1 Switching a REMOTE off from within REMOTE

12 The ATOM and System operating system interface 95

12.1 Introduction 12.2 Calling TRANSMIT 12.3 Receiving

vii 12.4 Immediate commands 12.5 Remote Subroutine Jump 12.6 Remote Procedure call 12.6.1 Operating system procedure call 12.7 Protection 12.8 Memory allooation 12.8.1 Page zero 12.8.2 Page two 12.8.3 Other locations

13 The file server interface 99

13.1 Introduction 13.2 The user environment - Handles 13.3 Definitions 13.4 Command line decoding 13.5 Simple commands 13.6 SAVE 13.7 LOAD 13.8 Other command line operations 13.9 Other functions 13.9.1 Save - code 1 13.9.2 Load - code 2 13.9.3 Examine - code 3 13.9.3.1 ARG = 0 13.9.3.2 ARG = 1 13.9.3.3 ARG = 2 13.9.3.4 ARG = 3 13.9.4 Catalogue header -code 4 13.9.5 Load as command - code 5 13.9.6 Find (OPEN) - code 6 13.9.7 Shut (CLOSE) - code 7 13.9.8 Get byte - code 8 13.9.9 Put byte - code 9 13.9.10 Get bytes and Put bytes - codes 10 and 11 13.9.11 Read random access info - code 12 13.9. 12 Set random access info - code 13 13.9.13 Read disc info - code 14 13.9.14 Read logged on users - code 15 13.9.15 Read date and time - code 16 13.9.16 Read "end of file" status - code 17 13.9.17 Read object info - code 18 13.9.18 Set file info - code 19 13.9.19 Delete object - code 20 13.9.20 Read user environment - code 21 13.9.21 Set user option - code 22 13.9.22 Log off - code 23 13.9.23 Read user info - code 24 13.9.24 Read File Server version number - code 25 Appendices

A Overview of the file server 114 B Command summary and abbreviations 115 C Error numbers 116 D BBC Microcomputer Machine operating system calls 118

9 Introduction

The ECONET is a low cost local area network capable of linking many computers together so that they can share information and resources. It has been designed for use with all Acorn Computers, and forms a valuable extension to the BBC Microcomputer System. In addition to low-level communication, the Econet provides a disc filing system and a printing service which can be shared by all machines attatched to the network. This manual describes the user commands and facilities provided by the network itself, the Acorn File Server and the Acorn Printer Servers. The early chapters are intended to help you understand the basics and start using the network as soon as possible. More technical information about the network and how it should be installed and maintained is provided in later chapters. In addition to this manual, the following documents are available: The Econet Reference Card - a summary of network user facilities The BBC Machine Printer Server Manual The Model B File Server Manual The Econet Technical Manual The Econet Installation Leaflet The information in the Econet Installation Leaflet is also contained in Chapter 8 of this manual, and should be read before attempting to install an Econet System.

Notes of errors and suggestions for improvement will be gratefully received. Comments should be sent to: Technical Documentation Department Acorn Computers Ltd Fulbourn Road Cherry Hinton Cambridge CB1 4JN

10 1 Getting going To get plugged into the Econet network you must have a computer suitably equipped as a user-station. At the moment, three types of computer can be connected to the network as a user-station. These are the BBC Microcomputer, the Acorn ATOM, and the Acorn Systems 3, 4 and 5. Whichever computer you use, it must be modified before using it with the Econet system. You may buy your computer already modifed (BBC Microcomputer models ANA 02, ANB 02 and ANB 04 are supplied complete with an Econet interface) or you may have it up-graded by your dealer. In either case, a computer for use as an Econet station must have the following: Econet interface hardware. A 5 pin din connector. A copy of the Econet Version III software. (Usually provided in an 8K EPROM for the BBC Microcomputer or a 4K EPROM for the Atom). To get going you will need a monitor or television to use with the computer. Plug in and switch on the computer, plug the TV or monitor into the computer and switch that on also. Plug the 5 pin DIN connector from the computer into an Econet socket. The pictures overleaf may help you get these bits and pieces sorted out. Obviously, you will need a network to plug in your station. Details on how to install a network are given in Chapter 8.

2 Figure 1.1 Plugging in a user station

12 1.1 Initialising the ECONET software

Once you have successfully connected your computer to the electrical supply and the network socket, it is necessary to start the ECONET software. This is done differently for each of the three types of user station so the next three sections tell you what to do for each machine. In addition, each machine can be started in a number of ways.

1.1.1 On the BBC Microcomputer

If on power-up either of the two following messages appears, then your computer has already automatically selected the Econet filing system. BBC Computer 32K

Econet station nnn

BASIC or

BBC Computer 32K

Econet station nnn No Clock

BASIC

The second is the No Clock message. It is not necessarily a serious problem. Section 1.1.4 tells you what to do.

If neither of these messages appears, then you will have to select the Econet system. This you can do by typing N BREAK, holding both keys down together, or CTRL N BREAK, holding all three keys down together. Alternatively you can type NET

If you use one of the methods involving resetting the machine ( pressing the BREAK key), you should obtain one of the two messages shown above. If you use the NET command no special message will appear.

NOTE- WELCOME TAPE If you wish to use the cassette filing system, for example to use the WELCOME tape, you must first do one of the following:

Either type

TAPE

or press SPACE BREAK (holding both keys down together) or press DELETE 13 BREAK (holding both keys down together). You can now continue as on page 11 of the BBC Microcomputer User Guide. If you later want to use any of the facilities of the Econet system you will have to select it b y one of the methods described above. This procedure is necessary because the BBC microcomputer can only deal with one filing system at a time and both the Econet and cassette systems are filing systems ( TAPE and NET select different filing systems - see Chapter 9).

1.1.2 - On the Atom

When you think you have connected everything together properly press BREAK on the keyboard of your computer. If everything is working you should get a message on the screen which looks something like this:-

ACORN ATOM ECONET 3.1A 235

Release/Version Number Station number

If all is not quite well you might get this message:

ACORN ATOM ECONET 3.1A NOCLK 235 )

Stands for No Clock

Section 1.1.4 tells you what to do if you get this No Clock message.

1.1.3 - On the Acorn Systems 3, 4 and 5

The System computers will not initialise the ECONET when you press BREAK. You need to make the computer jump to the first line of executable code in the ECONET software. This is accomplished by typing: GO E003 (Starts the software allowing communication over the network.)

After typing this you should get the message

Econet 3.10 NOS V.IIIA

You may probably also want to type one of the following: GO E000 (Enables just the network and returns "Econet 3.10") GO E009 (Enables the local disc filing system in the station and the network printer)

1.1.4 The No Clock message

14 This means that although your computer is switched on and contains the necessary hardware to connect to the network, a valid clock signal cannot be detected. There are two major reasons why you might get this problem. Number one is that you might have forgotten to plug your computer into the network with the 5 pin DIN plug. Easily remedied - plug it in and start again. Failing that, move on to major reason number two. There is no clock generator connected to the network to generate the clock signal. (One and only one clock generator must be connected to the network to do this). Seek out the person in charge of your network and ask for a clock signal. Probably you will not be the first person to ask as the absence of a clock signal will prevent everyone from using the network.

1.1.5 What next? Let us assume that you managed to connect to the network without a hitch. The cursor will be positioned directly after the > prompt for BASIC. You can now enter a program or type commands to make use of the network facilities. The most useful facility now available to you is the File Server. Chapter 2 tells you all about it.

15 2 The file server

2.1 What is the file server?

The file server is a machine code program written to run on an Acorn System 3, 4 or 5 computer or the BBC Microcomputer with a second 6502 processor and a disc system. It provides a disc file system which can be shared by the stations connected to the network. Common access to the disc drive(s) allows any authorised user to store and retrieve information.

The system supports a hierarchical directory structure, each user has as many directories as he requires. Simple protection facilities are provided to ensure that one users files can be protected from both other users and himself.

2.1.1 Purpose of this chapter

This chapter gives a complete description of the facilities provided by the file server. It starts with the simplest form of use and Introduces more complex operations in later sections. It is intended to be an instructional section rather than a reference manual or technical description. Accordingly, lists of error messages, syntax definitions etc. have been confined to later chapters. To find out how to use the file server simply to load and save files, it is suggested that you start at section 2.2, which gives a simple introduction to using files over the network. Section 2.3 introduces the idea of multiple directories, and further sections gradually deal with more complex features such as file security and library commands. Chapter 7 describes how to start and maintain the file server itself. This chapter is provided for the people responsible for running the file server, making sure the correct discs are available, and generally maintaining the file server for other users. Readers who are familiar with using filing systems and in particular hierarchical systems such as UNIX or TRIPOS may find that Appendix A gives a general introduction to the system sufficient to allow them to bypass some of the earlier sections. Details of how to use other facilities of the ECONET such as printer servers, the NOTIFY command etc. are covered in chapters 4 and 5.

2.1.2 Not starting the file server! The person in charge of the network usually starts the file server, so you dont have to. You can immediately start using the file server and if you are a registered user you can create files and directories of your own. If you ARE the person in charge of the network and you want to find out how to start the file server, read chapter 7.

16 2.2 Simple File Commands

2.2.1 A single directory

Although the file server supports a multi-directory file structure, it can be used in its simplest form just to store a list of files. This section describes the use of simple commands to save, load and inspect files in a single directory.

2.2.2 Commands

File server commands are identified by preceding them with a "" character. This distinguishes them from, for example, BASIC commands, PASCAL commands, or commands relating to a particular application program (e.g. an editor or assembler).

Commands can be used in BASIC programs (see section 5.2 for an example) and can be shortened by the "." character (see appendix B for abbreviations). If the File Server does not recognise a command, the message "Bad command" will be displayed and an error will occur.

2.2.3 Identifying Yourself

Before the file server can deal with file commands being sent to it from a station on the ECONET, it must know who is using that station. So the first thing to do before using files on the ECONET is to identify yourself. Each user has an identifier. Each identifier can be up to ten characters in length and must start with a letter. The user must remember his identifier which he sends to the file server using the I AM command. e.g. I AM ALEXANDER

ALEXANDER is now in communication with the file server.

This process of identification is known as "logging on" and will be refered to at various places in this manual.

2.2.4 SAVE

SAVE is a BASIC command which saves the current BASIC program text as a file. e.g.

SAVE "MYPROG" saves the current BASIC program as a file which belongs to the user who is logged on at this station.

2.2.5 SAVE

17 •SAVE saves an area of memory as a file. e.g.

SAVE MYDATA 3000+500 saves the area of memory from 3000 to 3500 as a file called MYDATA, owned by this station. In this case 3000 was the start address of the area in memory, 500 was its length. An alternative format for the command is: SAVE MYDATA 3000 3500 where 3000 is the start address as before, but the second parameter is the finish address of the section of memory you want to save, in this case 3500. This command is useful for saving machine code programs or data. It is also possible to specify a third parameter to a SAVE. This is the address where execution will start if the file is loaded as an executable command (see section 2.6.1). e.g.

SAVE BASIC C000+1000 C2B2 saves a machine code file which will be executed at C2B2 if loaded as a command.

The execution address can be left out of the command, in which case it defaults to the load address.

A fourth parameter may be specified which will be the address at which the file is loaded back (if this is to be different to the start address). For example:

SAVE PROG 3000 3500 5050 5000 will save a block of memory from 3000 to 3500. If the file is loaded it will be loaded at 5000 and the execution address if it is loaded as a command will be 5050. The load address parameter is optional. If it is to be specified, the execution address must also be explicitly given when the file is saved. 2.2.6 LOAD LOAD is a BASIC command which loads a file as a BASIC program. e.g.

LOAD "MATHS" loads a BASIC program called MATHS.

2.2.7 LOAD LOAD loads a file into a particular area of memory. e.g.

LOAD MYDATA will load the file MYDATA at the load address of that file. This address is either the start address given when the file was saved, or the load address if this was, specified (the fourth parameter of the SAVE command). 18 LOAD MYDATA 3200 will load MYDATA at location 3200.

2.2.8 Listing, Your Directory - CAT The CAT command provides a list (catalogue) of the files you have saved. A list (or set) of files in a filing system is known as a DIRECTORY, and each file is known as an ENTRY in the directory. (It is also possible to create directories as directory entries. This is dealt with in section 2.3). After the first three lines, the files are listed in alphabetic order, one per line with the access rights (see section 2.2.13) following each name. e.g. MATHS LR/ MYPROG WR/R

If no files are listed, the directory is empty (you have not saved any files). The first three lines contain information which is explained in detail later in this manual. The top line starts with the name of the directory being displayed. After this is the cycle number (which changes each time an entry is deleted or created) and then the word Owner or Public according to your access rights to this directory. The second line has the disc title and the auto-start option (see section 2.8). The third line shows the name of your currently selected directory and the name of the directory currently selected as the library.

DIRNAME (33) Owner THEDISCTITLE Option 0 (Off) Dir. CSDNAME Lib. LIBNAME

MATHS LR/ MYPROG WR/R

The meaning of ownership of a directory is dealt with in detail in section 2.4, but in the simple case you will always own your directory.

2.2.9 File Information - INFO INFO prints a list of information about a particular file. e.g.

INFO MATHS produces a string of information about the file MATHS. The format is:

19 The information may be split onto more than one line if the screen mode in use does not allow enough characters across the screen. For example in mode 7 (on the BBC computer) the information for a typical BASIC program might be: MATHS WR/R FFFF1200 FFFF801F 00044A 16:09:82 000450

The date is the date the file was last saved, and the System Internal Name (SIN) is the start sector of the file on the disc.

2.2.10 EX/INF

This is a program held in the Econet ROM on the BBC Microcomputer ( EX) and on the file server disc for ATOMs and Systems (INF). The command will cause the computer to do a INFO for all the files in the specified or current directory. A typical listing might be: DIRNAME (33) Owner THEDISCTITLE Option 0 (Off) Dir. CSDNAME Lib. LIBNAME

MATHS LR/ FFFF1200 FFFF801F 00044A 21:7:82 000450 MYPROG LR/R FFFF2900 FFFF2900 000351 13:7:82 00005D MYDATA LR/ FFFF1800 FFFF801F 000500 15:7:82 000043 PASCAL DL/ 00000000 00000000 000200 10:5:81 000075 where PASCAL is a directory (see section 2.3)

2.2.11 DELETE Simply deletes a file from the directory. e.g

DELETE MATHS

Once deleted a file cannot be restored. Locked files cannot be deleted and the message Entry locked is displayed if you try. You can only delete files in directories which you own.

2.2.12 RENAME This command changes the name of a file. For example:

RENAME OLDFILE NEWFILE changes the name of file "OLDFILE" to "NEWFILE". You can only rename files (not directories), you cant rename locked files and you cant rename across discs. You can rename a file and change its directory ( provided you have sufficient access). For example you can use something like:

20 RENAME A.OLDNAME B.NEWNAME which will move file "OLDNAME" in directory A and place it in directory B under the name "NEWNAME".

2.2.13 File Access - ACCESS

Many people will use a single file server, and you may want to protect important files from both other users and from accidents such as saving a data file into a program file or deleting an important program. It is therefore possible to set the ACCESS STRING for a file. e.g.

ACCESS MATHS LWR/WR

Each letter in the access string refers to a type of access to the file:

L - locked => the file cannot be deleted or overwritten. W - write => the file can be written to R - read => the file can be read.

The "/" character separates the OWNERS access (on the left) from PUBLIC access (on the right). So in the example, MATHS can be read and updated by both the owner and anybody else using the system.

If any character is not present in the string, the access it represents is taken to be unset. So:

ACCESS MATHS LR/ sets MATHS to be locked and readable only by the owner.

ACCESS MATHS sets MATHS to be unlocked and accessible by nobody.

When a file is saved, the access is set to a default of WR/.

Owner and public access is described more fully in section 2.4, but for simple use it is safe to assume that you own the files you have saved, and everybody else has only public access to them.

NOTE When a file is saved, the file server acts as though a new file is being created, and the old one, if present, is deleted. Thus you should protect against accidental saving with the LOCK character, not the WRITE character. Other people can never save into your files, whether they are locked or not (see section 2.4), unless they are system privileged (see section 7.7). The WRITE character refers to random access files (see section 2.10).

2.2.14 A Note on File Titles

File titles must be at least one character and up to ten characters 21 and can include upper and lower case alphabetic characters, numerics and the following punctuation symbols: ":"

MOTS "." and ":" have special meanings explained in section 2.3. Upper and lower case alphabetic characters are not distinguished. Thus " MATHS", "MaThS" and "maths" are all the same file name.

2.2.15 Multiple File Servers

All file server commands are addressed to a station number on the ECONET by the ECONET software. This station number is stored by the operating system, and is set by default to 254. If you wish to log on to a file server with a different number, type:

I AM 234 JOEY where 234 is the station number of another file server.

From that point on, all file server commands will be sent to station 234, unless you press CTRL and BREAK together. (Just BREAK on the Atom and System computers). When this happens, you remain logged on, but the station number reverts to 254, and it is neccessary to reset it, either by logging on again, or by directly changing the file server number at its location in your stations memory. On the BBC machine this is done by calling the appropriate OSWORD routine, on Atoms and Systems by poking the relevant memory locations. Full details are provided in Chapters 11 and 12. A soft reset (just BREAK) on the BBC Microcomputer does not reset the number of the selected file server. The ECONET can easily support several file servers, which have different numbers. They operate quite independently of each other, and one user can be logged on from one station to as many as required. This requires a knowledge of the operating system interface routines ( Chapters 11 and 12) and some understanding of the file server interface (Chapter 13). In particular it should be noted that the three user environment handles returned by each file server are unique to the file server that returned them. Thus when the file server number is changed, these handles must also be changed to the ones produced by the new file server. A single user can be logged on to the same file server from any number of stations, as the file server identifies people by their user identifier, not station number. The only limitation is the ability of the user to remember where he is logged on to what.

2.2.16 Monitor messages

The command OPT1 is used to set the "message switch" which controls the details of a message displayed whenever a file is loaded or saved.

OPT1,0 implies no messages are issued. OPT1,1 gives detailed information including load and execution addresses and length.

2.2.1722 Summary So far you have learnt how to use a single directory, save, load, delete and protect your files on it. In doing all this you may have come across some of the systems error messages. These are produced when the file server cannot understand your commands or something on the network is not working properly. All these errors are explained in Chapter 6. Common ones are NOT LISTENING, NO REPLY.

23 2.3. Creating and Using a Hierarchy of Directories

2.3.1 Directories Within Directories

In addition to containing files, a directory may have entries which are themselves directories. This allows any file owner to structure the way in which he keeps his files.

For example, the directory ALEXANDER, in addition to the files mentioned above, could have several directory entries corresponding to several different types of file. Pascal programs could be stored in a directory called PASCAL, and text-edited letters in a directory called LETTERS. The structure can be extended by, for example, creating further directories in LETTERS called MUM, DAD and BUSINESS to keep letters sent to various people. The only limit on the number of directories the system can handle is the amount of space on the disc, so each user can create as large and complex a structure as he thinks he needs to cope with his files. This type of structure, in which a directory can point to a number of directories "below" it, is called a HIERARCHICAL structure or tree structure. (see figure 2.1)

Throughout this section we will continue to use examples assuming that we are logged on as ALEXANDER, and are using the directory ALEXANDER.

2.3.2 Creating Directories The CDIR command creates a directory entry in the same way that SAVE creates a file entry. So:

CDIR PASCAL creates the directory PASCAL as an entry in ALEXANDER. Executing CAT will now list PASCAL as an entry among the files:

PASCAL DL/

The D before the access string indicates that it is a directory, and that its default access is simply "locked". W and R do not have any meaning for a directory. Executing INFO PASCAL gives information very similar to file information, except that the load and execute addresses, which again have no meaning, are zeros.

24 Figure 2.1 A hierarcical file structure

25 2.3.3 File Names

In order to use files from directories other than the current one, directory names and file names can be strung together to make one composite file name. The sections of the name are separated by the "." character and each section corresponds to a level (directory) of the hierarchy. (The only limit to the length of this string of names is the size of the input buffer). For example, with ALEXANDER selected, to access the file STATS1 in directory PASCAL, the title PASCAL.STATS1 is used. The section PASCAL is looked up in ALEXANDER, is found to be a directory, and STATS1 is then looked up in PASCAL. So the command:

SAVE PASCAL.STATS1 3000 +34 saves a file into the directory PASCAL.

The command

CAT PASCAL now lists the directory PASCAL (and shows STATS1 as an entry), and

INFO PASCAL.STATS1 gives us information about the file STATS1 in PASCAL.

Similarly, to load a particular business letter:

LOAD LETTERS.BUSINESS.TOACORN

Each section of a long file title is subject to the rules described in section 2.2.14 (10 characters only etc.).

2.3.4 Selecting Directories

In the examples so far, each time we quoted a file name (in SAVE, CAT etc.), it was looked up in the directory ALEXANDER. This would be inconvenient if we wished to do some work using the PASCAL files, and so it is possible to change the directory in which file names are looked up. The command used is DIR (select directory). e.g DIR PASCAL selects PASCAL as the CURRENTLY SELECTED DIRECTORY (CSD) in which all file names are now looked up. So, the command

LOAD STATS1 loads the Pascal file STATS1 from the directory PASCAL.

Similarly, CAT now produces a list of entries in PASCAL, not ALEXANDER. The first line of CAT also displays the last section of the current directory name, which is now PASCAL.

To return to the directory which was selected when ALEXANDER logged

26 on, the command DIR with no file name can be used.

2.3.5 The ROOT Directory and USERS ROOT Directory

So far we have only been concerned with a single users filing system stemming from a single directory, in this case ALEXANDER. In fact, a disc is itself a large file hierarchy with many users each having a personal sub-system such as the one described above. At the top of the system is a directory called the ROOT which contains a number of directories such as ALEXANDER. Each of these is a USERS ROOT DIRECTORY (URD) and forms the basis of a users personal file structure. The ROOT is referred to using the character "$" and can be incorporated in file titles like any other directory. This now makes it possible to look at and use other users files ( providing you have access - see section 2.4). For example:

CAT $.JOHN gives a catalogue of the directory JOHN in the root directory. This directory is not part of ALEXANDERs system and he only has public access so, for example, he cannot save files or create directories into it. A file title using the root is like any other file title and can therefore be used with any command. e.g.

DIR $.JOHN selects JOHNs directory as our current one (although we still dont have access to his files).

LOAD $.JOHN.BASIC.PROG1 loads one of JOHNs BASIC files. This would only be allowed if JOHN had allowed us READ access to his file.

CAT $ gives a list of the files and directories available in the root directory.

The root is created and put on the disc when the disc is initialised - see chapter 7.

2.3.6 Selecting Discs

A machine running the file server can support several disc drives. Each disc contains a complete filing system as described above, with a root at the top. Each person using the file server has a CURRENTLY SELECTED DISC, which determines which file system he is using. The currently selected disc name is displayed in the second line of a catalogue. The file server selects a disc for a user when he logs on by searching each disc on the system for a directory in the root which is the same as the user identifier. When such a directory is found, that disc becomes the users currently selected disc, and the 27 directory becomes both his users root directory and CSD. If no such directory is found, the disc in the left hand drive becomes the users current disc, and the root of that disc his URD and CSD.

To select a different disc, the SDISC command is used. Discs are identified by name, which is simply quoted after the command:

SDISC "FORM-THREE-MATHS"

If the disc is found, the same procedure for selecting URD and CSD is used as for logging on, and all file operations are interpreted in the new filing system.

It is also possible to temporarily access files on another disc, by quoting the disc name before a file title. (A disc name is distinguished in a file title by preceding it with the ":" character). e.g. CAT ":MATHS-DISC.JOEY.DATA" gives a catalogue of a directory located on a different disc. Once again, this is a general facility, so the following commands are valid:

DIR ":MATHS-DISC.JOEY"

LOAD ":FORM-THREE-MATHS.JOEY.STATS"

NOTE The root does not have to be specified when quoting a disc name (except when dealing with the root explicitly) so the above both refer to $.JOEY on the respective discs. To catalogue the root itself on FORM- THREE-MATHS: CAT ":FORM-THREE-MATHS.$"

2.3.7 Deleting Directories Directories can be deleted using the DELETE command, but ONLY if they themselves do not contain any entries. If you wish to delete a directory and its entire contents, this must be done entry by entry.

28 2.4. Owner and Public Access

2.4.1 Whats the difference? As we have seen, the owner of a directory may create entries in that directory (files or further directories), set the access to entries and has his own access governed by the " owner" field of any access string. If a user is using a directory which he does not own, he has PUBLIC access. This prevents him from creating entries (by saving or CDIR) and limits him to the "public" field of each access string. Also, he cannot set the access string of any entry.

2.4.2 Becoming the Owner If, when a user logs on, a directory is found in the root which matches his user identifier, he is given OWNER access to that directory, and any directories which are entries in that directory (it also becomes his CSD and URD - see 2.3.6). He is therefore owner of his complete directory system. However, he only has PUBLIC access to any directories or files outside that system, and cannot save files into somebody elses directory. e.g. After logging on as ALEXANDER and

executing: CAT $.JOHN the first line of the catalogue will contain the word "Public" after the directory name indicating that ALEXANDER only has public access to that directory. It should be noted that if ALEXANDER refers to his own files through the root, he will be treated like anybody else and given public access only. So: CAT $.ALEXANDER will also only display public access, whereas CAT with ALEXANDER selected as the users root directory will display owner access. To emphasise the point:

DIR $.ALEXANDER selects $.ALEXANDER as the CSD, but only with public access, 29 whereas: DIR selects the same directory, but with owner access, since DIR requests a return to the User Root Directory.

If there is no directory which matches the user identifier, the user is given public access only to the whole disc. This set of rules also applies when selecting a disc so that users files on one disc are protected from people using a separate disc on the same system.

30 2.5 Passwords

2.5.1 How they are used To prevent anybody who knows your user identifier from logging on as you and therefore gaining owner access to your files, it is possible to set a PASSWORD.

This is a string of up to 6 letters and numbers which should be knowr only to you and which must be quoted when you log on. e.g.

I AM ALEXANDER JULIE will allow ALEXANDER to log on if JULIE is his password. But:

I AM ALEXANDER and I AM ALEXANDER CRUST will produce the error "Wrong password".

Mote ON ATOMs and Systems you can prevent your password appearing on the screen by typing CTRL U to turn off the screen, then type your password and then type CTRL F to turn the screen on again. This is not possible on the BBC Microcomputer and you are advised to clear the screen after typing your password to prevent other people seeing it.

2.5.2 Setting the Password - PASS

To set a new password,

type: PASS

For example:

PASS "" JULIE sets ALEXANDERs password to JULIE, and PASS JULIE MOZART sets it to MOZART.

Also:

PASS MOZART removes ALEXANDERs password completely. Give careful thought to your choice of password if you want it to be effective. Your girl-friends name or your car registration are likely guesses for anyone trying to break into your files.

2.5.3 The Password File 31 The file server checks passwords by looking them up in a special file called the PASSWORD FILE. This exists on a disc selected by the file server when it is started up (see chapter 7). It is important to note that a password is therefore associated with a disc, and that if that disc is not in the system when a user tries to log on, he will be looked up in whatever password file is in use by the system.

If a user tries to log on when no password file exits on any of the discs on the system, the error "Password file not found" will occur. making sure that a suitable password file exists is part of the job of operating and maintaining the file server, described in chapter 7.

32 2.6 User Commands and Libraries

2.6.1 Introduction - Commands

It is possible to load and execute machine code programs in a single step simply by typing their name after the "" character indicating a file server command. e.g. PASCAL would load the file PASCAL from the current directory, and then jump to its execution address automatically, in this case starting the BBC Microcomputer Pascal interpreter program. If the name PASCAL had not been found in the currently selected directory, the file server would have then searched the currently selected LIBRARY.

2.6.2 Libraries

A library is simply a directory which is searched to look for command names not recognised by the file server program. When a user logs on, the file server will try to select the directory $.LIBRARY as the users current library. If it cannot find $.LIBRARY, the root will become the selected library. A different library can be selected using the command LIB. e.g.

LIB $.ALEXANDER.MYLIB

This command means that any command which the file server does not recognise is first searched for in the CSD and secondly in $.ALEXANDER.MYLIB. Only when it is not found in the library will the error "Bad command" occur. For example, typing:

EDIT means that a file called EDIT is looked for in the CSD, and if not found there, in $.ALEXANDER.MYLIB. If EDIT is found, it will be loaded and executed. Note that it is impossible to load and execute a directory, so an error would occur if a directory called EDIT existed in either of those directories. The library allows all users of the system to share useful application and utility programs easily. In particular, if command programs are kept in $.LIBRARY, using them is simply a matter of logging on and typing the program name as if executing any other file server command.

2.6.3 RUN and /

Machine code programs can be loaded and RUN using either of these commands. For example, typing:

33 RUN EDIT Or

/ EDIT will cause the file EDIT to be loaded and run. The file is looked up in the currently selected directory and then the current library in the same way as loaded commands.

2.7 EXEC and SPOOL These two commands are useful for dealing with BASIC files and commands. They are only available on the PBC Microcomputer.

2.7.1 EXEC

This command reads byte by byte all the information in a named file as if it were being typed on the keyboard. This is useful when you find that you are repeatedly typing the same sequence of commands. Instead you can build up an "EXEC" file consisting of these commands and type EXEC each time you want to use this sequence of commands. The argument can be a general file specification, that is, it can include directory name(s). For example

EXEC $.JOEY.COMM will read the file COMM in the directory JOEY byte by byte as if entered at the keyboard.

2.7.2 SPOOL

This command prepares a named file to receive the information subsequently displayed on the screen. This is useful for making an "EXEC" file (see section 2.7.1). For example, typing SPOOL FILE will open a file called FILE on the current directory, assuming that the user has sufficient access to do this (see section 2.4), and anything subsequently displayed on the screen will also be sent to FILE. Typing

SPOOL turns off spooling and closes FILE. It is importatn that you turn the monitor messages off when spooling otherwise they may interfere with the data you are trying to send to the file.

VOTE If you have a disc filing system attached to your computer, the disc system commands BUILD, LIST, DUMP, TYPE etc. are available - see the Disc Filing System manual for details.

34 2.8 Auto-start facilities

The facilities described in this section are available on the BBC Microcomputer only.

On the Econet system, auto-start may be selected to occur after either or both of the following actions (1) Resetting the machine with CTRL BREAK or BREAK or on power-up, with the Econet system fitted. (2) Logging on (as in section 2.2.3)

Whichever auto-start is chosen, a file called !BOOT will either be ignored, LOADed, RUN or EXECuted. The action on the file !BOOT is controlled by setting the users OPTION as described in the next section.

2.8.1 Setting option The option for a particular user is selected by that user by typing

OPT 4,n where n is a number in the range 0 to 3. The option numbers have the following meaning: OPTION 0 : ignores !BOOT OPTION 1 : LOADs !BOOT into memory at its load address OPTION 2 : RUNs !BOOT as a machine code file OPTION 3 : EXECs !BOOT

A users option can only be set by the user when logged on.

2.8.2 Auto-start when logging on

When a user logs on, a file called !BOOT is looked for in the users root directory. If the file is found, it is treated according to the option set for the user (see section 2.8.1). If there is no file called !BOOT in the users root directory, or if something goes wrong while loading, an appropriate error will occur (e.g. "Not found").

2.8.3 Auto-start when resetting the machine

If a BBC Machine is started by pressing SHIFT BREAK (both keys held down together), the Econet will attempt to auto-start without further intervention. It will do this by attempting to logon to the default file server as user BOOT. The action which is then taken depends on the option set for user BOOT and the contents of the !BOOT file in user BOOTs directory. If BOOT does not exist, or has no !BOOT file, there will be no auto-start, an error will be generated and the machine will hang until reset with BREAK etc. It should be noted that the user BOOT is no different from any other user name, and can be created by a system user in the normal manner (see 7.7.2). 35 It is possible to configure a BBC Machine so that the action on BREAK and SHIFT BREAK are swopped. This has the advantage that the BBC Machine will always try and auto-start (even on power-on) unless the SHIFT key is pressed. This feature is controlled by link 5 of the set of 8 links located at the right-hand front of the keyboard. These are numbered 1 to 8 from left to right and link 5 must be made to enable auto-start without the SHIFT key. Note that these links are only read by the operating system on hard reset of the machine, so changing the link and then simply pressing BREAK will have no effect on the auto-start state.

36 2.9. Utility Programs

2.9.1 Introduction

The commands described in the following section are command programs which are loaded and executed from a library as described in section 2.6. There are generally three versions of each command, for ACORN SYSTEMS, BBC Microcomputers and ATOMS. On the disc provided with the system, the ATOM versions will reside in $.ATOMLIB, the SYSTEM versions in $. SYSLIB and the BBC Microcomputer versions in the default library $. LIBRARY. Atom and System versions of each program are loaded into the calling machine at 2800. BBC versions are loaded into space reserved by the Network filing system.

2.9.2 INF

This command gives a list of all the entries in a directory and, in addition, provides information about each entry in a format similar to the INFO command. The "page mode" feature of the ATOM may come in handy here. INF can only accept file titles of up to 12 characters. Titles longer than-that will be truncated. This command corresponds to EX in BBC machines. See also section 2.2.10.

2.9.3 DISCS

This command will produce a list of the discs available in the current file server. The list will include the disc name and drive number.

2.9.4 USERS

This command will produce a list of the users currently logged on to the network. The list will include the users name, the privilege and the station number.

2.9.5 Network Utilities

These programs, although loaded from the file server, do not concern the filing system itself, and are described in chapter 5.

They include:

NOTIFY REMOTE VIEW PROT UNPROT

37 2.9.6 PS

This command sets the number of the station which printed output will be sent to (the Printer Server number). e.g.

PS 123 sets the Printer Server number to 123.

See section 4 for more information on printing over the network.

38 2.10 Random access

2.10.1 What is random access?

Random access is the name for reading or writing selected sections of a file. The disc systems available for the BBC, Atom and System computers all provide random access facilities. If you have written programs which make use of these random access facilities, they will run on the network without modification. The operating system primitives which provide these facilities are the same whether used with disc, cassette or over the network. The network filing system will intercept your programs input/output requests and re-direct these to the file server. The concept of file handles (referred to as channels on the BBC Microcomputer) is introduced here, followed by a general consideration of using random access in your BASIC programs. Assembler programmers should note that understanding the use of file handles (channels) is essential if you wish to directly address the file server.

2.10.2 Channels - Opening and Closing files

All the random access operations refer to files using a single byte number called a Channel (Handle on the Atoms and Systems). For example, the BGET# command in BBC BASIC takes a channel as an argument to indicate which file to read e.g. 340 nextletter%=BGET#C

This example is taken from the BBC Microcomputer user guide where all the relevant keywords are explained. In this case the letter C is the channel and the command will read the character in the file which is currently pointed to and assign its value to the variable nextletter%. The first step in using a file for random access is to assign a channel number to the file. Two commands are available in BBC BASIC to do this, OPENOUT and OPENIN. OPENIN is used for existing files which you want to read or update. A typical example of its use is: 230 X=OPENIN("cinemas")

This assigns the channel X to the file "cinemas" which must exist on the disc. After this line in your program you can use X as an argument in any of the read or write statements that you want to act on the file "cinemas". OPENOUT is different because the named file is deleted and recreated with 1K bytes space reserved on the disc. If the named file is not found in the directory, a new one is created. This command is generally used to initially create a file for using with random access. Afterwards OPENIN would be used to open the file. Note that files can only be opened for input and output if the user has sufficient access (see sections 2.2.13 and 2.4). The keyword OPENIN actually opens a file for update, so to use this keyword you need to have both read and write access. If you only have read access 39 to a file, and you wish to open it, you can use the operating system calls to open it for input only - see chapter 3.

The CLOSE# operation "deletes" a channel, so that the file server no longer recognises it and will give an error if used.

A single machine may have up to 8 valid handles at one time. However, three handles are taken up identifying the user environment (see chapter 13), so only 5 other objects can be opened at one time. It should be noted that one user can open a single object several times and can therefore have several different handles refering to it.

2.10.3 Random access in BASIC

The general principles of random access are as follows:

The File must be given a handle (channel). This is a single-byte reference number used by the operating system to identify an area in RAM for loading sections of the file. On the BBC Microcomputer the words OPENIN and OPENOUT do this, FIN and FOUT on Atoms and Systems. Files can only be opened if the user has sufficient access. The next task is to specify which section of the file you want to read or write. This is done by using a pointer to indicate a single byte in the file for the next read or write. Each file is considered as series of single bytes. In BBC BASIC the word used is PTR#. On Atoms and Systems it is PTR. It is used by assigning it a value, e.g. PTR# = 1000

This means that the next byte to be read or written is number 1000 in the file.

There are a number of operators in both the BBC and Atom/System BASIC which allow you to read and write. These are: BBC Atom/System INPUT# GET PRINT# PUT BGET# BGET BPUT# BPUT SGET SPUT

Finally there is a function which tells you when the end of the file has been reached. (i.e. you have read or advanced the pointer to the last byte in the file). This is EOF# in BBC BASIC.

Later versions of BBC BASIC will have an extra keyword called OPENUP. This opens a file for update (reading and writing). OPENIN then becomes open for input only. Full explanation of how to use these BASIC keywords for random access is provided in the reference manual which comes with your computer. Mote Multiple byte access using the operating system call OSBGBP (see section 3.4) is considerably faster than single byte access (as used 40 by BASIC). The operating system call OSBGBP should therefore be used where speed is important.

2.10.4 Using the Pointer

The file sequential pointer (PTR# or PTR) mentioned above can be used to select the next byte to be accessed or to extend the length of a file. If you wish to read a particular byte of a file, all you have to do is assign the correct number to the variable PTR# or PTR. The next byte read will be from the position indicated by the value of this variable. The pointer is incremented by one after each byte is read.

If you wish to extend a file then all you need to do is to assign a value to PTR# (or PTR) which is beyond the end of the file. The variable EXT#, which usually gives the number of bytes in a file will give the total length of the file. An example will probably serve to clarify this. Assume that the file " DATA" has been set up containing 20 bytes of information. If you open the file using A=OPENIN"DATA" then the variables will have the following values:

PTR#A - 0 EXT#A - 20

If you now type

PTR#A = 100 the end of the file will be moved to make the file 100 bytes long and the variables will have the following values:

PTR#A - 100 EXT#A - 100 and the file will be longer by 80 bytes. The extra 80 bytes will all be zeros. Note This can only be done if the file is opened for update (using OPENIN) otherwise you will get the "Outside file" error. If you try to extend a file too far, you may get the error message "Disc full" if there is not sufficient space on the disc.

2.10.5 Interlocks This is a very important feature included in the Econet system. Consider the following situation which might conceivably arise. You open a file to read using random access facilities. At the same time, somebody else opens the same file and starts to update it. It could easily happen that, between your reading one part of the file and another, the person updating the file changes some of the entries. This could produce disastrous results if some of the later data is 41 supposed to match up with some of the earlier data (for example a list of names and telephone number stored as a list of names followed by a list of corresponding numbers).

To prevent this situation arising, a system of interlocks is implemented. The system used is called "multiple reader, single writer and is a common method of protecting multi-user systems. This works as follows: If a file has been opened for reading then anybody else can open the file for reading, but NOT for writing. If a file has been opened for writing, then nobody else (including yourself) can open the same file.

If you are not able to open a file for the above reasons you will get the error "Already Open".

Note The BBC BASIC command OPENIN opens a file for updating, which includes writing. Thus a file can only be opened once using OPENIN.

42 3 Using the File Server from Assembler

This chapter describes the operating system interface for the filing system for the BBC Microcomputer. The interfaces for the ATOM and Systems are described in ATOMIC THEORY AND PRACTICE and the System DOS Manual respectively. This chapter describes a series of operating system calls which can be used to open, close, read and write files.

Files are treated as a sequence of 8-bit bytes. Files can be accessed in one operation (using OSFILE) or a byte at a time (using OSBGET or OSBPUT).

Associated with each file are various parameters. The load address specifies where a file should be loaded into memory if accessed using OSFILE. The execution address is meaningful only if the file contains executable code, in which case this address represents an entry point if the file should be loaded and entered. The extent of the file is its size in bytes (which may take the value zero).

In addition, associated with each open file is its sequential pointer. This represents the index (counting the beginning of the file as zero) of the next byte to be accessed. A number of operating system calls are provided for dealing with files. In the following sections, A refers to the processors accumulator, X and Y to the X and Y registers. The flags are referred to by the letters C, N, V and Z. All addresses are in 6502 order, i.e. lo-byte first, hi-byte last. 3.

1 OSFIND

Call address FFCE (indirects through 021C).

Opens a file for reading/writing/update.

The value in A determines the type of operation.

(i) A non-zero A<>0 causes a named file to be opened. X (10-byte) and Y (hi-byte) point to the name of the file to be opened. The name is represented by a string terminated by a carriage-return (ASCII 0D).

If A=40 the file is opened for input only. If A=80 the file is opened for output only. If A=•C0 the file is opened for reading and updating. ON EXIT, A<>0 implies that the file was successfully opened (A contains the handle for the opened file which must be provided when operating on the file).

43 A=0 implies that the file could not be opened. C, N, V and Z become undefined. The interrupt state is preserved. However, interrupts may be enabled during the operation.

(ii) A zero

A=00 causes (a file)/(files) to be closed.

If Y<>0 the file whose handle is given by Y is closed. If Y=0 all open files are closed (including SPOOL Sand EXEC files). ON EXIT, C, N, V and Z become undefined. The interrupt state is preserved. However, interrupts may be enabled during the operation.

3.2 OSFILE

Call address FFDD (indirects through 0212).

Load/Save data, Inquire/Alter catalogue information.

X and Y point to a control block (X lo-byte, Y hi byte):-

Notes: (i) The character string is terminated by 0D.

A contains a job description parameter.

FF :- LOAD file to given address/files address. The low byte of the execution address (offset 06) determines whether the file should be loaded to its own address (if non-zero) or to the supplied load address (if zero). The files catalogue information will be written into the control block, see 44 item 5. 00 :- SAVE data to file. If start address = end address then the data is of zero length. The files catalogue information will be written into the control block, see item 5. 01 :- WRITE catalogue information for file. Length information is not alterable. 02 :- WRITE the load address to the catalogue information. Only the Load address is required. 03 :- WRITE the execution address to the catalogue information. Only the execution address is required. 04 :- WRITE the attributes to the catalogue information. Only the attributes are required. 05 :- READ files catalogue information. The Load address (offset 02), Execution address (offset 06), Length in bytes (offset 0A), Attributes (offset 0E) and Type (in A) are returned for the particular file. 06 :- DELETE the file and return catalogue information. Returns 0 in A if object did not exist, otherwise non-zero. The attribute of a file is a 4 byte (32 bit) item whose bits refer to the state of the protection flag, and the date. The bottom 8 bits have the following meanings:- bit meaning 7 Undefined. 6 Undefined. 5 = 0 -> the file is not writeable by other users. = 1 -> file is writeable by other users. 4 = 0 -> the file is not readable by other users. = 1 -> the file is readable by other users. 3 = 0 -> the file is not locked. = 1 -> the file is locked. 2 Undefined. 1 = 0 -> the file is not writeable by you. = 1 -> the file is writeable by you. 0 = 0 -> the.file is not readable by you. = 1 -> the file is readable by you.

The Econet filing system places the date information in the next 16 bits using the following format: Lo-byte - days Hi-byte, bits 0 to 3 - months Hi-byte, bits 4 to 7 - years since 1981.

The Type is a byte which describes the object which was found for READ:

Type 0 is no object found Type 1 is file found Type 2 is directory found

3.3 OSARGS

Call address FFDA (indirects through 0214). 45 Reads/Writes an OPEN files attributes. X points to 4 locations in zero page. Y contains the file handle. A specifies the type of operation. If Y is non-zero then OSARGS will do one of the following jobs on the file of which Y is the handle: A=00 read sequential pointer A=01 write sequential pointer A=02 read extent

The result being returned in the zero-page location pointed to by X. If the pointer is set to past the end of the file then the file will be padded such that intervening bytes read as nulls, A will be returned as 0 if the operation is performed, otherwise it will be left unchanged. If Y is zero then OSARGS will do one of the following jobs on the filing system: A=00 Return type of filing system in A 0- No current filing system 1- 1200 baud CFS 2- 300 baud CFS 3- ROM filing system 4- Disc filing system 5- Econet filing system 6- Teletext/Prestel Telesoftware A=01 Return address of rest of command line at X.

3.4 OSBGBP

Call address FFD1

Write/read a group of bytes to/from a specified open file.

ON ENTRY, X(lo-byte) and Y(hi-byte) point to an instruction block:

A determines the type of operation: A=01 Put byte using byte offset A=02 Put byte ignoring byte offset A=03 Get byte using byte offset A=04 Get byte ignoring byte offset A=05 Read title,option A=06 Read current directory A=07 Read current library 46 A=08 Read file names

ON EXIT,

A = 0 implies operation attempted

A=01 to 04 The number of bytes is modified to show how much data has not been transferred (usually zero), the pointer value is updated (i.e. old pointer plus the amount transferred), and the offset is set to its current value. The offset is only defined after the call if you are not using the sequential file pointer. A=05 This returns in the area pointed at by the pointer the disc title of the currently selected disk and the users option. It is returned in this form:-