Chapter 10 : Machine Code Reference Section =========================================== BBC MOS Interface This section is intended as a full and detailed handbook of the machine code interface to the network filing system. It covers the filing system interface, which is (in theory at least) the same as the interface to disc, tape or any other filing system. It also covers the network communication functions which are network specific. The section assumes knowledge of the BBC operating system, BASIC (including the indirection operators - see chapter 39 of the BBC User Guide), assembler and control blocks. Because this section is a reference section, it is not necessary to understand all of it at once. Instead it should be possible to look up a certain call as it is needed. Network Versions ---------------- There are three main Network filing system ROMs available for the BBC computer. These are: NFS version 3.34 NFS version 3.60 Advanced NFS (Only available for the Master, Econet Terminal & Compact) (see OSARGS A=2 Y=0 and *HELP for testing the version) Although they are intended to control the same operations there are some important differences. Because all versions are common, programs should be written so that they will work on all. Memory Addresses ---------------- The filing system assumes that addresses in a remote or local machine are 4 bytes long. For a normal BBC computer this means that the top 16 bits are not relevant, but when a 2nd processor is used only the address &FFFFxxxx specifies the I/O processor. For the 6502 2nd processor the address &0000xxxx specifies the language processor. In general if the I/O processor is the intended destination then &FFFFxxxx should always be used. Unless otherwise specified, multi-byte numbers are stored low byte first. For an Acorn Master & Acorn Econet Terminal the I/O processor is located at address &FFFFxxxx and the screen RAM is located at address &FFFExxxx. Calling Operating System Routines --------------------------------- These routines handle all the input and output to the Econet system. All routines require the Decimal flag (D) to be clear on entry. The Interrupt flag (I) is always preserved (but interrupts may be enabled during the call). Some operating system routines require a control block; a small area of memory set up to hold the parameters to be used by the routine. An area of memory must be preserved for the control block, filled with the parameters you want, and pointers to the area given to the routine. The information for most calls is described here in the form of a control block. The number on the left hand side is refering to the offset from the start of the control block. To set up a control block an area of memory should be reserved before the call is performed. It is simple to use the BASIC indirection operators to set up the values in the control block. The program listed below performs a peek (i.e. a transfer of data from the memory of a remote machine to the memory of the local machine) by using the following control block: 0 +-----------------------------+ | &81 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to start of | | local buffer | 8 +-----------------------------+ | Pointer to end of | | local buffer | 12 +-----------------------------+ | Pointer to start of | | remote machine's buffer | 16 +-----------------------------+ 10 DIM blk% 15 :REM Reserve a block of data 20 INPUT "Station: "station% 30 blk%?0=&81 :REM Control byte for peek 40 blk%?1=0 :REM Port number for immediate operation 50 blk%!2=station% :REM Insert station number 60 blk%!4=&FFFF7C00 :REM Start of MODE 7 screen (not scrolled) 70 blk%!8=&FFFF8000 :REM End of MODE 7 80 blk%!12=&FFFF7C00 :REM Start of MODE 7 in remote machine 90 100 X%=blk% :REM X points to low byte 110 Y%=X% DIV 256 :REM Y points to high byte 120 A%=&10 :REM Set accumulator 130 CALL &FFF1 :REM Call OSWORD Note that the above program does not check that the transmit operation worked. For a complete description of the peek operation see sections 10.9 and 10.14. Issue 29 Apr 1987 10-1 SJresearch Summary of all calls for Econet =============================== Name Call Address Section Description ---------------------------------------------------------------------------- OSGBPB &FFD1 10.1 Read/write group of bytes to a file, read user's environment OSFIND &FFCE 10.2 Open/close file for random access OSBGET &FFD7 10.3 Get byte from file (Use OSGBPB if possible) OSBPUT &FFD4 10.4 Write byte to file (Use OSGBPB if possible) OSARGS &FFDA 10.5 Read/write file's arguments (using a handle) OSFILE &FFDD 10.6 Read/write file's arguments OSCLI &FFF7 10.7 Send string to command line interpreter OSWORD &FFF1 10.8 Network Specific commands 10.9 Transmit data (A=&10) 10.10 Receive data (A=&11) 10.11 Read arguments (A=&12) 10.12 Read/write station information (A=&13) 10.13 Send to File Server (A=&14) OSBYTE &FFF4 10.14 Poll transmission and reception 10.15 Transmitting 10.16 Receiving 10.17 Port numbers 10.18 The Bridge 10.19 Printers 10.20 The File Server Interface 10.21 Password entry format 10.22 Application Notes 10.23 Netmon 10.24 Econet Protocols 10.1 OSGBPB Call Summary ========================================================================== Entry point: &FFD1 Indirected via &21A On entry -------- A =Reason code YX points to a control block 13 bytes long. Do not put the control block in page zero. There is a bug in NFS 3.34 such that OSGBPB will not work at all if this is done. Value in A Function A=1 Write block using offset A=2 Write block ignoring offset A=3 Read block using offset A=4 Read block ignoring offset A=5 Read currently selected disc title and boot option A=6 Read directory A=7 Read library A=8 Read specified number of file names On exit ------- A = Return code indicating whether the requested function is supported by the currently selected filing system. If A=0 then the operation was attempted. A is returned unchanged if that function is not available. YX undefined. Control block is modified on completion. On some filing systems the carry flag is set on reaching the end of the file/directory, this should not be relied on. To write software that is compatible with all filing systems the only method of finding whether all the files have been read is to look at the contents of (control block + 4). Issue 29 Apr 1987 10-2 SJresearch Write data giving offset OSGBPB A=1 ========================================================================== General description ------------------- This call writes a block of data from RAM to a file, specifying where in the file to put the bytes. On entry -------- A=1 YX point to the control block shown below: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Address of data | 5 +-------------------------------+ | Number of bytes to transfer | 9 +-------------------------------+ | Offset in file | 13 +-------------------------------+ On exit ------- The sequential pointer (PTR#) will have been updated to point immediately beyond the last byte written. If the operation succeeded the control block is: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Old Address + Number of | | bytes transfered | 5 +-------------------------------+ | Number of bytes not | | transfered (should=0) | 9 +-------------------------------+ | Old offset + | | Number of bytes transfered | 13 +-------------------------------+ Example ------- The procedure below uses this call to write a string to the file opened as handle%. DEF PROCwrite_string(handle%,$data%,offset%) LOCAL A%,X%,Y% blk%?0=handle% blk%!1=data% blk%!5=LEN($data%) blk%!9=offset% X%=blk% Y%=X% DIV 256:A%=1 IF (USR(osgbpb) AND &FF)<>0 THENPROCsimulate_osgbpb(blk%) ENDPROC The procedure below can be used on systems that do not support OSGBPB (e.g.TAPE). DEF PROCsimulate_osgbpb(blk%) LOCAL I% PTR#?blk%=blk%!9 FOR I%=blk%!1 TO blk%!1+blk%!5 BPUT#?blk%,?I% NEXT ENDPROC The following program uses the above procedure to create a file called 'filename' and write two strings to it. 10 DIM data% 255 :REM Maximum size of my string (actually 256 bytes) 20 DIM blk% 12 :REM My control block 30 osgbpb=&FFD1 50 out_ch%=OPENOUT"Filename" 60 PROCwrite_string(out_ch%,"This is a test",0) 70 PROCwrite_string(out_ch%,"Another piece of text",&22A) 80 CLOSE#out_ch% 90 END Compatibility between Filing Systems ------------------------------------ Not supported on TAPE, ROM or some non-Acorn DFS. Note on the Acorn File Server a write beyond the end of the file will give an EOF (end of file) error. Issue 29 Apr 1987 10-3 SJresearch Write data OSGBPB A=2 ========================================================================== General Description ------------------- This call writes a block of data to a file using the current pointer (i.e. the value returned by PTR#). On entry -------- A =2 YX point to the control block shown below: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Address of data | 5 +-------------------------------+ | Number of bytes to transfer | 9 +-------------------------------+ | Ignored | 13 +-------------------------------+ On exit ------- The sequential pointer (PTR#) will have been updated to point immediately beyond the last byte written. If the operation succeeded the control block is: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Old Address + Number of | | bytes transfered | 5 +-------------------------------+ | Number of bytes not | | transfered (should=0) | 9 +-------------------------------+ | Corrupt | 13 +-------------------------------+ Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM or some non-Acorn DFS. Read Data giving offset OSGBPB A=3 ========================================================================== General description ------------------- This call reads a block of data from a file into RAM, from a specified offset in the file (i.e. ignoring PTR#). On reaching the end of the file the carry flag (C) is set, and the amount of data not transferred is returned in the control block. An EOF (End of file) error will be returned if the offset is past the end of the file. If the offset of a file is equal to the extent, then no bytes will be transferred. A=3 YX point to the control block shown below: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Location to put data | 5 +-------------------------------+ | Number of bytes to transfer | 9 +-------------------------------+ | Offset in file | 13 +-------------------------------+ On exit ------- If the operation was successful the control block is: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Old Location + Number of | | bytes transfered | 5 +-------------------------------+ | Number of bytes not | | transfered (should=0) | 9 +-------------------------------+ | Old offset + | | Number of bytes transfered | 13 +-------------------------------+ The number of bytes not transferred will be zero unless the end of file has been reached; in which case all bytes from the offset up to the end of the file will have been transferred, and the number not transferred is the difference between the number originally asked for and the number actually transferred. Note that an area of memory large enough to hold the entire quantity of data asked for will always be corrupted, so it is inefficient to request many more bytes than are expected to be available. NFS 3.60 does NOT return the correct result for EOF# after this call. The only way of checking to see if the End Of File has been reached, is to read the result from the control block (bytes 5-8 inc.). Compatability between Filing Systems ------------------------------------ Not supported on TAPE or ROM or some non-Acorn DFS. Note that the Acorn DFS does not corrupt more memory than is required to hold the data loaded, whereas the NFS will always transfer the amount of data requested. Therefore programs which request more bytes than there is memory space to hold may work on the DFS but crash with NFS. Issue 29 Apr 1987 10-4 SJresearch Read Data OSGBPB A=4 ========================================================================== General description ------------------- This call reads a block of data to a file, at the position given by the sequential pointer (PTR#). On entry -------- A =4 YX point to the control block shown below: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Location to put data | 5 +-------------------------------+ | Number of bytes to transfer | 9 +-------------------------------+ | No data needed but will be | | modified | 13 +-------------------------------+ On exit ------- If the operation was successful the control block is: 0 +-------------------------------+ | File Handle | 1 +-------------------------------+ | Old Location + Number of | | bytes transfered | 5 +-------------------------------+ | Number of bytes not | | transfered (should=0) | 9 +-------------------------------+ | Corrupt | 13 +-------------------------------+ Number of bytes not transferred and memory corruption as for OSGBPB A=3. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE on ROM or some non-Acorn DFS. Note that not all filing systems return C=1 to indicate that the end of file has been reached. It is strongly recommended that to find whether the end of file has been read the number of bytes not transferred is checked for a non-zero value. Read CS disc name OSGBPB A=5 ========================================================================== General description ------------------- This call returns your currently selected disc name and your boot option. On entry -------- A =5 YX point to the control block shown below: 0 +-------------------------------+ | xxx | 1 +-------------------------------+ | Address where data will be | | loaded | 5 +-------------------------------+ | xxx | 9 +-------------------------------+ | xxx | 13 +-------------------------------+ xxx indicates that no parameter is required. On exit ------- C undefined. The control block is left unchanged [no it's not] The address pointed to by the control block is modified as shown below: 0 +-------------------------------+ | Length of disk title (n) | 1 +-------------------------------+ | Disk title (max 16 | | characters) | (n+1) +-------------------------------+ | Your boot option as set by | | *OPT4 | (n+2) +-------------------------------+ The disc name is normally 16 characters padded with spaces. It is possible for the disc name to have spaces as significant characters, e.g. 'Wombat 2' (although on the network it would not be possible to use this name). Therefore to read the disc tide the name should be read backwards, stripping off spaces until the first non-space character. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Issue 29 Apr 1987 10-5 SJresearch Read CSD name OSGBPB A=6 ========================================================================== General description ------------------- This call returns your currently selected directory name. On entry, A =6 YX point to the control block shown below: 0 +-------------------------------+ | Undefined | 1 +-------------------------------+ | Address to put the data | 5 +-------------------------------+ | Undefined | 9 +-------------------------------+ | Undefined | 13 +-------------------------------+ There is a bug in NFS version 3.34 which sometimes causes the error 'No reply'. To get around this problem the following fix should be used before calling OSGBPB. .fix_bug LDA #2:LDY #0:JSR &FFDA \ Call OSARGS to read version of NFS CMP #2:BNE not required \ Fix not required if not version 3.34 LDX #block MOD 256 \ Fix NFS workspace by writing LDY #block DIV 256 \ an &CB to location &B8 LDA #6:JSR &FFF1 \ OSWORD to write to I/O processor .not_required (Rest of the code) .block EQUD &FFFF00B8 \ Write &CB to location &FFFF00B8 EQUB &CB N.B. It is essential that the version is checked before modifying this location, because it cannot be guaranteed that the use of this location will not change. On exit ------- The address pointed to by the control block is modified as shown below: 0 +-------------------------------+ | Length of drive number(v)=0 | | on NFS | 1 +-------------------------------+ | ASCII coded drive number | | This field is not present | | on NFS | 5 +-------------------------------+ | Length of directory name (n) | | (Usually 10 characters) | 9 +-------------------------------+ | Directory name | | (Usually 10 characters) | 9 +-------------------------------+ | Ownership | | (0=Owner, &FF=Public) | 9 +-------------------------------+ The directory title may be padded with spaces. Issue 29 Apr 1987 10-5 SJresearch Example ------- The following program will print out the currently selected directory, and drive number, on all filing systems that support the call. 10 REM Read currently selected directory name 20 REM This program is compatible with all filing systems 30 REM (C) A.J.Engeham, SJ Research 40 REM_____________________________________________________ 50 60 osgbpb=&FFD1 70 DIM blk% 17,buffer% 100 80 blk%?0=0 90 blk%!1=buffer% 100 blk%!5=0 110 blk%!9=0 120 X%=blk%:Y%=X% DIV 256 130 A%=6 140 IF (USR(osgbpb) AND &FF)=6 THEN P."Not supported":END 150 pos%=0 160 PROCread("Current drive number is : ") 170 PROCread("Currently selected directory is : ") 180 END 190 200DEF PROCread(string$) 210 LOCAL V%,result$,I% 220 V%=buffer%?pos% 230 pos%=pos%+1 240 IF V%=0 THEN ENDPROC 250 FOR I%=pos% TO pos%+V%-1 260 result$=result$+CHRS(I%?buffer%) 270 NEXT 280 pos%=pos%+V% 290 PRINTstring$;result$ 300ENDPROC Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Note that early versions of ADFS do not return the ownership byte. Read LIB name OSGBPB A=7 ========================================================================== General description ------------------- This call returns your currently selected Library. On entry -------- A =7 YX point to the control block shown below: 0 +-------------------------------+ | Undefined | 1 +-------------------------------+ | Address to put the data | 5 +-------------------------------+ | Undefined | 9 +-------------------------------+ | Undefined | 13 +-------------------------------+ On exit ------- The address pointed to by the control block is modified as shown below: 0 +-------------------------------+ | Length of drive number (v)=0 | | on NFS | 1 +-------------------------------+ | ASCII coded drive number | | This field is not present | | on NFS | 5 +-------------------------------+ | Length of Library name (n) | | (Usually 10 characters) | 9 +-------------------------------+ | Library name | | (Usually 10 characters) | 9 +-------------------------------+ | Ownership | | (0=Owner, &FF=Public) | 9 +-------------------------------+ Example ------- See OSGBPB with A=6. The Library name may be padded with spaces. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Issue 29 Apr 1987 10-7 SJresearch Read objects OSGBPB A=8 ========================================================================== General description ------------------- This call reads file/directory names from your currently selected directory. On entry -------- A =8 YX point to the control block shown below: 0 +-------------------------------+ | 0 | 1 +-------------------------------+ | Location to put the data | 5 +-------------------------------+ | Maximum number of file | | names to transfer | 9 +-------------------------------+ | Which file to start on | 13 +-------------------------------+ On exit ------- The control block is modified as shown below. 0 +-------------------------------+ | Cycle number | 1 +-------------------------------+ | Pointer to the end of data | 5 +-------------------------------+ | Number of files NOT | | transfered | 9 +-------------------------------+ | Which file to ask for next | 13 +-------------------------------+ The file names may be padded with spaces. 0 +-------------------------------+ | Length of filename (n) | 1 +-------------------------------+ | Filename | (n+1) +-------------------------------+ | Length of filename | | (if asked for) | (n+2) +-------------------------------+ | Filename | +-------------------------------+ | . | | . | | . | +-------------------------------+ Example ------- The program shown below will print out all the file names of your currently selected directory. Note that, because the starting file is the first one in the directory, this program will produce the same results for the Disc Filing System as the Network Filing System. DIM blk% 13,buffer% 20 blk%!9=0 :REM Start at the first file REPEAT blk%?0=0 :REM Cycle number returned here blk%!l=buffer% blk%!5=l :REM Number of files to read X%=blk%:Y%=blk% DIV 256 A%=8:CALL &FFD1 IF blk%!5=0 THEN ?(buffer%+l+buffer%?0)=13:PRINT $(buffer%+l) UNTIL blk%!5=1 Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Entry number are not guaranteed to be sequential; the only value which should be used in general are 0 and values returned by a previous call. In the special case of Econet, entry numbers start from zero and ascend in steps on 1 to specify objects in alphabetical order. The carry flag is NOT valid on exit. The DFS is misleading in this respect, although C happens to be significant on DFS systems, it is not an official Acorn feature. Issue 29 Apr 1987 10-8 SJresearch 10.2 OSFIND Call Summary ========================================================================== Entry point: &FFCE Indirected via &21C On entry -------- A=Type of operation. On exit ------- A=file handle if successful. A=0 not possible to open file. C,N,V,Z are undefined. Contents of control block are preserved. Value in A Function A=0 Close file specified by Y register A=&40 Open file for input A=&80 Open file for output (i.e. create new file deleting old file) A=&C0 Open file for update (i.e. input and output). Close files OSFIND A=0 ========================================================================== General description ------------------- If Y=0 then the call closes all open files but will not close directory context handles. If Y<>O then the call closes the file handle, or context handle, held in Y. This call is called by CLOSE#Y in BASIC. On entry -------- A=0 Y=handle to close (0 to close all files) On exit ------- A,X,Y undefined Compatibility between Filing Systems ------------------------------------ Supported on all filing systems. Y=0 does not work on some versions of Master DFS, as it does not inform the MOS that any open EXEC file has closed. A fix is to ensure *EXEC or *FX119 (close SPOOL and EXEC files) is used before using CLOSE#0. Indiscriminate use of CLOSE#0 is bad programming practice and should be avoided. Issue 29 Apr 1987 10-9 SJresearch Open file for input OSFIND A=&40 ========================================================================== General description ------------------- Returns a handle for a file whose name is in memory, pointed to by YX. This handle can then be used for reading bytes from that file. The handle can also be used as a context handle to describe your environment on your File Server. This call is called by the BASIC 2 keyword OPENIN. On entry -------- A=&40 YX point to a control block containing a string terminated by a carriage return (&OD). On exit ------- A=file handle if successful A=0 if unable to open file X,Y undefined C,N,V,Z undefined Compatibility between Filing Systems ------------------------------------ Supported on all filing systems. Open file for output OSFIND A=&80 ========================================================================== General description ------------------- Create a file with the name given at memory address YX and returns a handle for that file. The file is opened for writing. Any previous file of that name is deleted. This is called by the BASIC keyword OPENOUT. On entry -------- A=&80 YX point to a filename terminated by a carriage return (&OD). On exit ------- A=file handle if successful A=0 if unable to open file X,Y undefined C,N,V,Z undefined Compatibility between Filing Systems ------------------------------------ Not supported on ROM, or any other read only filing systems. Issue 29 Apr 1987 10-10 SJresearch Open file for update OSFIND A=&C0 ========================================================================== General description ------------------- Returns a handle for a file whose name is pointed to by YX. The file is opened for both reading and writing. This is called by the BASIC 2 keyword OPENUP and the BASIC 1 keyword OPENIN. On entry -------- A=&C0 YX point to a control block terminated by a carriage return (&OD). On exit ------- A=file handle if successful A=0 if unable to open file X,Y undefined C,N,V,Z undefined Example ------- The example shows how to OPENUP a file for BASIC 1 and BASIC 2. DIM dummy% 80 $dummy%="" INPUT "Filename : "dummy$ P.FNopenup(dummy$) END DEF FNopenup($dummy%) LOCAL A%,X%,Y% X%=dummy% Y%=dummy% DIV 256 A%=&C0 = (USR(&FFCE) AND &FF) Compatibility between Filing Systems ------------------------------------ Not supported on ROM. TAPE treats the open for update as an open for output (i.e. OSFIND with A=&80). 10.3 OSBGET Read Byte ========================================================================== Entry point: &FFD7 Indirected via &216 General description ------------------- This call reads one byte from a file, using a handle returned from an OSFIND call. The file pointer (PTR#) is incremented. On entry -------- Y=file handle On exit ------- X,Y preserved If successful A=byte retrieved from file, C=0 If the end of the file is reached A=254, C=1 If an attempt to read past the end of file is made, an 'EOF' error will be returned. Compatibility between Filing Systems ------------------------------------ Supported on all filing systems. Although this call is supported on the Econet it is very slow, it is essential that wherever possible OSGBPB is used. This is because the file server takes time to process each byte, and time is taken to send each byte across the network; if the file server (if it isn't one of our multitasking file servers) is processing someone else's command your machine will wait in the mean time. If *PUTGET is active, or your machine has ANFS, then the indirection vector will be modified so that the data is read from the fileserver using OSGBPB, and later retrieved from a buffer in memory. Issue 29 Apr 1987 10-11 SJresearch 10.3 OSBPUT Write Byte ========================================================================== Entry point: &FFD4 Indirected via &218 General description ------------------- This call puts one byte to a file, using a handle returned from an OSFIND call. The file pointer (PTR#) is incremented On entry -------- Y=file handle A=byte to put On exit ------- A,X,Y are preserved N,V,Z,C are undefined Compatibility between Filing Systems ------------------------------------ Supported on all filing systems except ROM, and other read only filing systems. Although this call is supported on the Econet it is very slow, it is essential that wherever possible OSGBPB is used. This is because the file server takes time to process each byte, and time is taken to send each byte across the network; if the file server (if it isn't one of our multitasking file servers) is processing someone else's command your machine will wait in the mean time. If *PUTGET is active, or your machine has ANFS, then the indirection vector will be modified so that the data is read from the fileserver using OSGBPB, and later retrieved from a buffer in memory. 10.3 OSARGS Call Summary ========================================================================== Entry point &FFDA Indirects via &214 On entry -------- Value in Y Value in A Function Y=0 A=0 Return filing system number Y=0 A=1 Return rest of command line Y=0 A=2 Return version of NFS ROM Y=0 A=3 Return libfs filing system number Y=0 A=4 Return disk space used Y=0 A=5 Return disk free space Y=0 A=&FD Y=0 A=&FE Y=0 A=&FF Ensure all files are up to date on the media Y<>0 A=0 Read sequential pointer Y<>0 A=1 Write sequential pointer Y<>0 A=2 Read extent of file Y<>0 A=3 Write extent of file (ANFS only) Y<>0 A=4 Read current amount of space allocated to file (ANFS only) Y<>0 A=5 Read EOF Y<>0 A=6 Ensure size of open file Y<>0 A=7 Y<>0 A=8 Y<>0 A=&80 Read internal information (ANFS only) Y<>0 A=&FD Y<>0 A=&FE Y<>0 A=&FF Ensure file is up to date on the media On exit ------- A=0 if the operation supported (except A=0, Y=0) otherwise A is preserved X,Y are preserved C,N,V,Z are undefined Issue 29 Apr 1987 10-11 SJresearch Return Filing System Number OSARGS A=0 Y=0 ========================================================================== General description ------------------- This calls returns, in A, the number of your current filing system. On entry -------- A=0 Y=0 On exit ------- A=filing system number X,Y preserved N,V,Z,C undefined Value in A Meaning 0 No current filing system 1 Cassette, 1200 baud 2 Cassette, 300 baud 3 ROM 4 Disc 5 NFS 6 Teletext/Prestel 7 IEEE 8 Advanced Disc 9 Host 10 VFS Video disc 12 Acacia RAM 16 HADFS To select filing system 'n' use OSBYTE with A=&8F, X=&12, Y=n. Compatibility between Filing Systems ------------------------------------ Supported on all filing systems. Acorn DFS 0.90 does not respond to OSBYTE &8F to select the filing system. End of line parameter OSARGS A=1 Y=0 ========================================================================== General description ------------------- This call set the zero page locations (pointed to by X on entry to the call) to point to the parameter at the end of the last command line. Unfortunately, there is a bug in version 3.34 of the NFS ROM such that the call returns the pointer pointing to the text immediately after the last *. For example, in the command line '********VIEW 23' it would point to the 'V' in VIEW. On all other filing systems that support this call, and later versions of the NFS ROM, the call returns the pointer pointing to the '2' in the 23. On entry -------- A=1 Y=0 X=Zero page location On exit ------- A=0 if call supported otherwise A is preserved. X,Y preserved N,V,Z,C undefined Example ------- The program below shows a typical method of getting round the problem with different versions of the NFS. osargs=&FFDA .error BRK \ 'entry' is the start address EQUB 0 \ Your error number EQUS "Syntax : ":BRK \ Your error message .entry LDA #1:LDY #0:LDX #zp \ zp is a zero page location JSR osargs \ Get command line LDY #0:LDA #0:JSR osargs \ Find what filing system CMP #5:BNE new_nfs \ It's o.k. if not NFS LDA #2:LDY #0:JSR osargs \ Read version of NFS \ (See OSARGS A=2 Y=0) CMP #2:BNE new_nfs \ Branch if the NFS is >3.34 .loop1 INY:LDA (zp),Y CMP #&0D:BEQ error \ If no parameter supplied then error CMP #ASC" ":BNE loop1 \ Repeat until space is found .loop2 INY:LDA (zp),Y CMP #ASC" ":BEQ loop2 \ Deal with spaces between \ command and parameter .new_nfs \ Your program starts here! \ Next character is at (zp),Y The above program will only work if executed in the I/O processor. If this is to be tube compatible then the block of memory, holding the end of the command line parameter, must be transferred across the tube. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Issue 29 Apr 1987 10-13 SJresearch Version of NFS OSARGS A=2 Y=0 ========================================================================== General description ------------------- This call returns the version of NFS ROM. On entry -------- A=2 Y=0 On exit ------- A=Version of NFS X,Y preserved N,V,Z,C undefined Value in A Meaning A=1 ANFS, NFS version 3.40 or greater A=2 NFS version 3.34 or call not supported Compatibility between Filing Systems ------------------------------------ Supported on NFS only. If you are trying to write programs which are to be compatible on all filing systems then you must check to see if the current filing system is the network (OSARGS with A=0, Y=0) before issuing this call For example, if the call is being used to get around the bugs in NFS version 3.34 then first check the filing system, if the filing system is not network then do not use this call, because the result of the call will be A=2 (call not supported). Issue 29 Apr 1987 10-11 SJresearch Return libfs filing system number OSARGS A=3 Y=0 ========================================================================== Return disk space used OSARGS A=4 Y=0 ========================================================================== Return disk free space OSARGS A=5 Y=0 ========================================================================== Read internal info OSARGS A=&FD Y=0 ========================================================================== Return last drive number used OSARGS A=&FE Y=0 ========================================================================== Update all files OSARGS A=&FF Y=0 ========================================================================== General description ------------------- Ensures that any data for all open files held temporarily in RAM is transferred to disc. Useful in programs which may run for many hours and do not wish to risk losing data if the power fails etc. On entry -------- A=&FF Y=0 X ignored On exit ------- A=0 if operation successful, otherwise A=&FF X,Y preserved N,V,Z,C undefined Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Although this call is supported on the standard version of the NFS ROM the call has no effect because the data will always be up to date on the file server, this is not the case with the ANFS ROM because OSBGET and OSBPUT are buffered internally. Issue 29 Apr 1987 10-12 SJresearch Read PTR# OSARGS A=0 Y<>0 ========================================================================== General description ------------------- Read the sequential pointer (PTR#) leaving the result in four consecutive zero page locations specified in X. On entry -------- A=0 Y=file handle (see OSFIND) X=zero page location On exit ------- A=0 X,Y preserved N,V,Z,C undefined The address pointed to by X (zero page location) holds the sequential pointer in 6502 order as a 4 byte value. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Write PTR# OSARGS A=1 Y<>0 ========================================================================== General description ------------------- Write the sequential pointer (PTR#) of a file using the value held in four consecutive zero page locations pointed to by X. On entry -------- A=1 Y=file handle (see OSFIND) X=zero page location On exit ------- A=0 if operation successful, otherwise A=1 X,Y preserved N,V,Z,C undefined The contents of the zero page locations are preserved. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Issue 29 Apr 1987 10-15 SJresearch Read extent OSARGS A=2 Y<>0 ========================================================================== General description ------------------- Reads the extent of a file leaving the result in four consecutive zero page locations specified in X. On entry -------- A=2 Y=file handle (see OSFIND) X=zero page location On exit ------- A=0 if operation successful, otherwise A=2 X,Y preserved N,V,Z,C undefined The address pointed to by X (zero page location) holds the extent of the file in 6502 order as a 4 byte value. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Write extent OSARGS A=3 Y<>0 ========================================================================== General description ------------------- Writes the extent of a file (called by BASIC'S EXT#) using the value given in four consecutive zero page locations specified in X. On entry -------- A=3 Y=file handle (see OSFIND) X=zero page location On exit ------- A=0 if operation successful, otherwise A=3 X,Y preserved N,V,Z,C undefined The contents of the zero page locations are preserved. Compatibility between Filing Systems ------------------------------------ This call is only supported on the Advanced Network filing system, ADFS, HADFS and RISC OS filing systems. However a call of this nature requires cooperation from the file server as well, and not all versions of File Server support it either. Issue 29 Apr 1987 10-16 SJresearch Read space OSARGS A=4 Y<>0 ========================================================================== General description ------------------- Reads the amount of space currently allocated to a file. On entry -------- A=4 Y=file handle (see OSFIND) X=zero page location On exit ------- A=0 if operation successful, otherwise A=4 X,Y preserved N,V,Z,C undefined Compatibility between Filing Systems ------------------------------------ This call is only supported on the Advanced Network Filing system, HADFS and RISC OS filing systems. Read EOF OSARGS A=5 Y<>0 ========================================================================== Ensure size of open file OSARGS A=6 Y<>0 ========================================================================== Convert handle to filename OSARGS A=7 Y<>0 ========================================================================== Inform change in filestamp OSARGS A=8 Y<>0 ========================================================================== ANFS Internal Info. OSARGS A=&80 Y<>0 ========================================================================== General description ------------------- Return internal information held by the Advanced Network filing system ROM. On entry -------- A=&80 Y=handle to return information on. X points to four bytes in zero page. On exit ------- The first byte has the handle in file server format. The second and third byte hold the fileserver number. The fourth byte holds the following information: Bit 0 is the sequence number Bit 1 is the 'known to be a dir' flag bit Bit 2 is the 'thought to be URD' bit Bit 3 is the 'thought to be CSD' bit Bit 4 is the 'thought to be CSL' bit Bit 5 is the 'current context' bit Bit 6 is the EOF error bit, set if the next BGET will fail Bit 7 is the write flag, set means writable to Compatibility between Filing Systems ------------------------------------ This call is only supported on the Advanced Network Filing system ROM and HADFS. Issue 29 Apr 1987 10-16 SJresearch Read/Write internal info OSARGS A=&FD Y<>0 ========================================================================== Read info on handle OSARGS A=&FE Y<>0 ========================================================================== Update file OSARGS A=&FF Y<>0 ========================================================================== General description ------------------- Ensures that any data held temporarily in RAM is transferred to disc. Useful in programs which may run for many hours and do not wish to risk losing data if the power fails etc. On entry -------- A=&FF Y=handle to return information on. X ignored On exit ------- A=0 if operation successful, otherwise A=&FF X,Y preserved N,V,Z,C undefined Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Although this call is supported on the standard version of the NFS ROM the call has no effect because the data will always be up to date on the file server, this is not the case with the ANFS ROM because OSBGET and OSBPUT are buffered internally. 10.6 OSFILE Call Summary ========================================================================== Entry point &FFDD Indirected via &212 On entry -------- A=Reason code YX point to the control block Value in A Function A=0 Save a block of memory as a file using the information provided in the parameter block. A=1 Write the information in the parameter block to the catalogue entry for an existing file (i.e. file name and address). A=2 Write the load address (only) for an existing file. A=3 Write the execution address (only) for an existing file. A=4 Write the attributes (only) for an existing file. A=5 Read a file's catalogue information, with the file type returned in the accumulator. The information is written to the parameter block. A=6 Delete the named file. A=7 Create a file (ANFS only) A=8 Create a directory (ANFS only) A=&FD A=&FE A=&FF Load file to given address. Issue 29 Apr 1987 10-18 SJresearch Save a file OSFILE A=0 ========================================================================== General description ------------------- This call saves a block of memory as a file, using the information provided in the control block. On entry -------- A=0 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Reload address | 6 +-------------------------------+ | Execution address | 10 +-------------------------------+ | Start address of data | 14 +-------------------------------+ | End address of data | 18 +-------------------------------+ On exit ------- A=object type X,Y,C undefined The control block is filled with the file information of the saved file. Compatibility between Filing Systems ------------------------------------ Not supported on read only systems such as ROM filing system. Change file info OSFILE A=1 ========================================================================== General description ------------------- This call is used to change the reload address, execution address and attributes of a file to the values given. On entry -------- A=1 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Reload address | 6 +-------------------------------+ | Execution address | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Attributes | 18 +-------------------------------+ The attributes of a file are 8 bits corresponding to the following values: Bit Access set on NFS Meaning if set 7 Undefined on NFS (locked for other users on some filing systems) 6 Undefined on NFS (executable by other users on some filing systems) 5 W public access The file is writeable by other users 4 R public access The file is readable by other users 3 L The file is locked 2 E Undefined on network (executable by you on some filing systems) 1 W owner access The file is writeable by you 0 R owner access The file is readable by you On exit ------- A=object type X,Y,C undefined The control block is filled with the file information. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or read only filing systems such as ROM. Some filing systems only change the access byte of the attributes, some filing systems allow the modification date to be changed as well. Issue 29 Apr 1987 10-19 SJresearch Change reload address OSFILE A=2 ========================================================================== General description ------------------- This call is used to change the reload address of a file to that specified in the control block. On entry -------- A=2 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Reload address | 6 +-------------------------------+ | Ignored | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Ignored | 18 +-------------------------------+ On exit ------- A=object type X,Y,C are undefined The control block is filled with the file information. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or read only filing systems such as ROM. Change execute address OSFILE A=3 ========================================================================== General description ------------------- The call is used to change the execution address of a file to that given in the control block. On entry -------- A=3 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Ignored | 6 +-------------------------------+ | Execution address | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Ignored | 18 +-------------------------------+ On exit ------- A=object type X,Y,C undefined The control block is filled with the file information. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or read only filing systems such as ROM. Issue 29 Apr 1987 10-19 SJresearch Change attributes OSFILE A=4 ========================================================================== General description ------------------- This call is used to change the attributes of a file or directory. On entry -------- A=4 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Ignored | 6 +-------------------------------+ | Ignored | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | File attributes | 18 +-------------------------------+ See OSFILE A=1 for meaning of file attribute bits. On exit ------- A=object type X,Y,C undefined Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or read only filing systems such as ROM. Some filing systems only change the access byte of the attributes, some filing systems allow the modification date to be changed as well. Read catalogue info OSFILE A=5 ========================================================================== General description ------------------- This call is used to read a file or directory's catalogue information into a control block. On entry -------- A=5 YX point to the control block shown below :- 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Ignored | 6 +-------------------------------+ | Ignored | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Ignored | 18 +-------------------------------+ On exit ------- A=0 if object not found, A=1 if object was a file, A=2 if object was a directory. X,Y,C undefined 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Load address | 6 +-------------------------------+ | Execution address | 10 +-------------------------------+ | Length | 14 +-------------------------------+ | Access | 15 +-------------------------------+ | Creation date | 17 +-------------------------------+ | Undefined | 18 +-------------------------------+ The attributes are 8 bits corresponding to the following values: Bit Access set on NFS Meaning if set 7 L Locked for other users 6 R public access Executable by other users 5 W public access Writeable by other users 4 R public access Readable by other users 3 L Locked for you 2 R owner access Executable by you 1 W public access Writeable by you 0 R owner access Readable by you Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or ROM. Issue 29 Apr 1987 10-21 SJresearch Delete object OSFILE A=6 ========================================================================== General description ------------------- Deletes the filename pointed to by the control block. On entry -------- A=6 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Ignored | 6 +-------------------------------+ | Ignored | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Ignored | 18 +-------------------------------+ On exit ------- X,Y,C undefined If object not found then A=0 otherwise A=object type and control block updated as with OSFILE A=5. Compatibility between Filing Systems ------------------------------------ Not supported on TAPE or read only filing systems such as ROM. Create file OSFILE A=7 ========================================================================== General description ------------------- This call is the same as the save operation (OSFILE A=0) except that no data is transfered. Consequently the newly created file is filled with zeros. On entry, A=7 YX point to the control block shown below: 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Reload address | 6 +-------------------------------+ | Execution address | 10 +-------------------------------+ | Start address of data | 14 +-------------------------------+ | End address of data | 18 +-------------------------------+ On exit ------- A=object type X,Y,C undefined The control block is filled with the created file's information. Compatibility between Filing Systems ------------------------------------ Not supported on read only systems such as ROM filing system, nor on NFS 3.34/3.60, early versions of File Server, early versions of DFS. Some filing systems may not fill the new file with zeros, and may just allocate it the required disk space. Issue 29 Apr 1987 10-21 SJresearch Create directory OSFILE A=8 ========================================================================== General description ------------------- This call is the same as the *CDIR command and creates a directory. On entry, A=8 YX point to the control block shown below: 0 +-------------------------------+ | Address of directory name | 2 +-------------------------------+ | Ignored | 6 +-------------------------------+ | Ignored | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Ignored | 18 +-------------------------------+ On exit ------- A=object type X,Y,C undefined The control block is filled with the created directory's information. Compatibility between Filing Systems ------------------------------------ Not supported on read only systems such as ROM filing system, nor on NFS 3.34/3.60, early versions of File Server, not support on filing systems with subdirectories, such as DFS. Read internal information OSFILE A=&FD ========================================================================== Verify file OSFILE A=&FE ========================================================================== Load file OSFILE A=&FF ========================================================================== General description ------------------- This calls loads a file at a specified reload address, or, if the low byte of the execution address parameter is not zero, at the file's own reload address. The control block is updated with the file's catalogue information (load address, execution address, length, attributes). On entry -------- A=&FF YX point to the control block shown below: 0 +-------------------------------+ | Address of directory name | 2 +-------------------------------+ | Address to load to | 6 +-------------------------------+ | &00 to load to supplied load | | address | | <>&00 to load to file's own | | load address | 7 +-------------------------------+ | Ignored | 10 +-------------------------------+ | Ignored | 14 +-------------------------------+ | Ignored | 18 +-------------------------------+ On exit ------- A=1 to indicate file found X,Y,C undefined 0 +-------------------------------+ | Address of filename | 2 +-------------------------------+ | Load address | 6 +-------------------------------+ | Execution address | 10 +-------------------------------+ | Length | 14 +-------------------------------+ | Attributes | 18 +-------------------------------+ Compatability between Filing Systems ------------------------------------ Supported by all filing systems. ANFS does not update the control block correctly after loading the file. 10.7 OSCLI Command line ========================================================================== Entry point &FFF7 Indirected via &208 General description ------------------- This call is used to send a command line to the Operating system or your currently selected filing system. This is the equivalent of a direct command with a ' *' in front of it On entry -------- A is undefined YX point to the command line to be interpretated. On exit ------- A,X,Y,C undefined Example ------- 10 DIM s% 80 20 PROCoscli("CAT") 30 END 40 50 DEF PROCoscli($s%) 60 X%=s%:Y%=s% DIV 256 70 CALL &FFF7 80 ENDPROC If the procedure is used instead of the keyword OSCLI, then it can be guaranteed that this part of the program will not be sensitive to version 1 of BASIC. Compatibility between Filing Systems ------------------------------------ Supported on all filing systems. Issue 29 Apr 1987 10-21 SJresearch 10.8 OSWORD Call Summary ========================================================================== Entry point &FFF1 Indirects via &20C On entry -------- Value in A Control byte Function A=&10 &81 READ a block of memory from a remote machine A=&10 &82 WRITE a block of memory to a remote machine A=&10 &83 CALL location and send argument block to remote machine A=&10 &84 User procedure call to a remote machine A=&10 &85 Operating system procedure call to a remote machine A=&10 &86 HALT a remote machine A=&10 &87 START a remote machine (after a Halt) A=&10 &88 Read the machine type and version number of a remote machine A=&10 &89 Read remote ARM register contents (RISC OS only) A=&11 Receive block operations A=&12 Reading arguments A=&13 Reading/writing station information A=&14 &00 Communicate with File Server A=&14 &01 Send Text message A=&14 &02 Cause remote error Calls with A=&10 are all varients of Transmit see section 10.15 for details of the necessary polling and retry techniques. 10.9 Peek OSWORD A=&10 (Control byte=&81) ========================================================================== General description ------------------- This returns a block of memory from a remote machine into the local machine. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &81 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to start of | | local buffer | 8 +-----------------------------+ | Pointer to end of | | local buffer | 12 +-----------------------------+ | Pointer to start of | | remote machine's buffer | 16 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Issue 29 Apr 1987 10-24 SJresearch Poke OSWORD A=&10 (Control byte=&82) ========================================================================== General description ------------------- This sends a block of memory from the local machine into the remote machine. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &82 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to start of | | local buffer | 8 +-----------------------------+ | Pointer to end of | | local buffer | 12 +-----------------------------+ | Pointer to start of | | remote machine's buffer | 16 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Remote JSR OSWORD A=&10 (Control byte=&83) ========================================================================== General description ------------------- This call sends an argument block to a remote machine, then jumps to a location in the remote machine. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &83 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to start of | | local buffer for arguments | 8 +-----------------------------+ | Pointer to end of | | local buffer for arguments | 12 +-----------------------------+ | Address to CALL in remote | | machine | 16 +-----------------------------+ After this call the remote machine is protected against procedure calls and OS procedure calls until the parameter block is read. The program in the remote machine must read the parameter block (OSWORD A=&12) before exiting (with a RTS), otherwise the remote machine will remain protected. If the remote machine is a BBC microcomputer then the address to call must be in the I/O processor. Although interrupts are disabled in the remote machine, they should be enabled if the routine is going to take much longer than 1mS to complete. The maximum size of the argument block is 128 bytes. On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Issue 29 Apr 1987 10-24 SJresearch Remote procedure OSWORD A=&10 (Control byte=&84) ========================================================================== General description ------------------- This passes a block of memory to a remote machine and causes an event (number 8) in that machine. The program in the remote machine must intercept the event number (procedure number held in YX) and read the argument block (OSWORD A=&12) before exiting with an RTS. Note that the argument block must be read even if there are no arguments, because the Rx control block will not be reopened until this has happened. Machines with Econet version 3.34 may crash, because stations greater than 240 can override the machine protection, therefore they can overwrite the argument block before it is read. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &84 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to start of | | local buffer for arguments | 8 +-----------------------------+ | Pointer to end of | | local buffer for arguments | 12 +-----------------------------+ | Procedure number | 16 +-----------------------------+ In the remote machine the Accumulator (A register) holds the event number (which will be 8). X will hold the low byte of the procedure number and Y will hold the high byte. On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Example ------- The first program uses the user procedure call to cause an event in a remote machine (held in the variable stn% : line 60). Note that the second program MUST be running in the remote station, otherwise the remote station will become protected. 10 REM Program to send Events to a remote machine 20 DIM blk% 100,buffer% 100 30 osword=&FFF1:osbyte=&FFF4 40 50 REPEAT 60 stn%=4 : cntr%=100 70 REPEAT 80 blk%?0=&84 : blk%?1=0 : blk%!2=stn% 90 blk%!4=buffer% : blk%!8=buffer%+4 100 blk%!12=2 :REM Procedure number 110 X%=blk% : Y%=blk% DIV 256 : A%=&lO 120 CALL osword 130 cntr%=cntr%-1 140 UNTIL FNpoll_transmit OR cntr%=0 150 160 UNTIL cntr%=0 170 PRINT"! can't send an event to machine ";stn% 180 END 190 200 DEF FNpoll_transmit 210 LOCAL A%:A%=&32 220 REPEAT V%=(USR(osbyte) AND &FF00) 230 UNTIL (V% AND &8000)=0 240 =((V% AND &7F00)=0) This program is to be run in the remote machine. When an event occurs, the event routine increments a location on the screen. 10 REM Detecting an event sent through the Econet 20 REM (C) A.J.Engeham, SJ Research 30 REM ___________________________________ 40 DIM code &100,buffer 100 50 osword=&FFF1:osbyte=&FFF4 60 MODE 7 70 PROCassemble 80 CALL set_up_event 90 PRINT"The event routine has been set up" 100 PRINT" - waiting for event to happen" 110 END 120 130 DEFPROCassemble 140 FOR pass=0 TO 2 STEP 2 150 EVENTV=&220:zp=&70 160 P%=code 170 [OPT pass 180 .set_up_event 190 LDA EVENTV:STA zp 200 LDA EVENTV+1:STA zp+1 \ Save old event handling routine 210 SEI \ Changing Event vector interupts \ must be disabled. Issue 29 Apr 1987 10-26 SJresearch 220 LDA #handle_eco MOD 256:STA EVENTV 230 LDA #handle_eco DIV 256:STA EVENTV+1 260 CLI \ Vector done reenable interupts 270 LDA #14:LDX #8:JSR osbyte \ Enable Econet events 280 RTS 290 300 \******** Event handling routine ********* 310 .handle_eco 320 PHP 330 CMP #8:BNE not_econet_event \ If not 8 then the event was not caused 340 \ by the Econet 350 PHA:TXA:PHA:TYA:PHA \ It was the Econet so save registers 370 CPX #2 \ Check for User procedure call 2 380 BNE dud_eco_call \ Not the procedure call sent from 390 CPY #0:BNE dud_eco_call \ my machine 400 INC &7E00 \ Do something exciting 410 .dud eco call 420 LDX #buffer MOD 256:LDY #buffer DIV 256 \ YX points to the buffer 430 LDA #&12:JSR osword \ Read arguments 440 PLA:TAY:PLA:TAX:PLA \ Restore registers 450 .not_econet_event 460 PLP \ Restore flags 470 JMP (zp) \ Pass event back to MOS to handle 480 ] 490 NEXT 500 ENDPROC Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Remote Insert key OSWORD A=&10 (Control byte=&85) ========================================================================== General description ------------------- This call inserts a byte into a remote machine's keyboard buffer and is used by the 'send a line of text' command (OSWORD A=&14 Control byte=1), which should usually be used in preference to this calL See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &85 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to buffer | 8 +-----------------------------+ | Pointer to buffer + 1 | 12 +-----------------------------+ | &00 | 16 +-----------------------------+ The buffer (which is 1 byte long) holds the byte to send to the remote station. On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Example ------- 10 REM Insert a character into a remote machine's keyboard buffer 20 REM (C) A.J.Engeham, SJ Research 30 REM___________________________________________________________ 40 50 DIM blk% 16,buffer% 1 60 osword=&FFF1:osbyte=&FFF4 70 INPUT"Station number : ";stn% 80 PRINT"Character to send : "; 90 ?buffer%=GET 100 tries%=20 Issue 29 Apr 1987 10-27 SJresearch 110 REPEAT 120 blk%?0=&85 130 blk%?1=0 140 blk%!2=stn% 150 blk%!4=buffer% 160 blk%!8=buffer%+1 170 blk%!12=0 180 X%=blk%:Y%=X% DIV 256 190 A%=&10:CALL osword 200 tries%=tries%-1 210 REPEAT 220 A%=&32 230 UNTIL (USRosbyte AND &8000)=0 240 tries%=tries%-1 250 UNTIL (USRosbyte AND &7F00)=0 OR tries%=0 260 IF tries%=0 PRINT"Unable to send character":END 270 PRINT"Character sent" 280 END Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Start REMOTE OSWORD A=&10 (Control byte=&85) ========================================================================== General description ------------------- This call is used to start a REMOTE. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &85 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to buffer | 8 +-----------------------------+ | Pointer to buffer + 1 | 12 +-----------------------------+ | &01 | 16 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Issue 29 Apr 1987 10-28 SJresearch Update workspace OSWORD A=&10 (Control byte=&85) ========================================================================== General description ------------------- This call causes a remote machine to write the state of its screen to a position in its Econet workspace (whence it can be read by the local machine by PEEKing this workspace). See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &85 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to buffer | 8 +-----------------------------+ | Pointer to buffer + 1 | 12 +-----------------------------+ | &02 | 16 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ In the remote machine the data is written to the address (in the I/O processor) pointed to by locations &9E and &9F plus &E9. This data is shown below: 0 +-----------------------------+ | Address of top of screen | 2 +-----------------------------+ | Palette (physical colours | | defined on screen) | 18 +-----------------------------+ | Mode number (0-7) | 19 +-----------------------------+ | Address of start of screen | 21 +-----------------------------+ | Mark/Space for colours | 23 +-----------------------------+ Example ------- 10 REM Info, about a remote m/c : Demonstration for OS procedure 2 20 REM (C) A.J.Engeham, SJ Research 30 REM _____________________________________________________________ 50 DIM blk% 100,buffer% 100 60 INPUT"Station number ",stn% 70 osword=&FFF1:osbyte=&FFF4 80 90 PROCtransmit(&85,1, 2) 100 PROCtransmit(&81,2, &FFFF009E) 110 PROCtransmit(&81,30,&FFFF0000+(buffer%!0 AND &FFFF)+&E9) 120 130 MODE 7 140 PRINT"Machine number ";stn% 150 PRINT" MODE ";buffer%?18 160 PRINT" Address of start of screen=&";~buffer%!19 AND &FFFF 170 PRINT" Address of top of screen=&";~buffer%!0 AND &FFFF 180 PRINT'"Palette"'"_______"'"Logical Physical" 190 FOR I%=0 TO 15 200 PRINTTAB(3);I%TAB(12);I%?(buffer%+2) 210 NEXT 220 END 230 240 DEFFNpoll_transmit 250 LOCAL A%:A%=&32 260 REPEAT V%=(USR(osbyte) AND &FF00) 270 UNTIL (V% AND &8000)=0 280 =((V% AND &7F00)=0) 290 300 DEFPROCtransmit(cb%,no of bytes%,start%) 310 LOCAL cntr%,X%,Y%,A% 320 cntr%=20 330 REPEAT 340 blk%!0=cb% 350 blk%!2=stn% 360 blk%!4=buffer% 370 blk%!8=buffer%+no_of_bytes% 380 blk%!12=start% 390 X%=blk%:Y%=blk% DIV 256 400 A%=&10:CALL osword 410 cntr%=cntr%-1 420 UNTIL FNpoll_transmit OR cntr%=0 430 IF cntr%=0 THENPRINT"Machine not listening":END 440 ENDPROC Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Issue 29 Apr 1987 10-29 SJresearch Fatal Error OSWORD A=&10 (Control byte=&85) ========================================================================== General description ------------------- This causes a fatal error in a remote machine. It is easier to use the high level fatal error call (OSWORD A=&14 Control byte=2). See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &85 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to buffer | 8 +-----------------------------+ | Pointer to buffer + 1 | 12 +-----------------------------+ | &03 | 16 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Halt OSWORD A=&10 (Control byte=&86) ========================================================================== General description ------------------- Halts all non-interrupt operations in the I/O processor of a remote machine. If a Tube is running on the remote machine, then that will continue running until it tries to communicate with the I/O processor. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &86 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Issue 29 Apr 1987 10-29 SJresearch Continue OSWORD A=&10 (Control byte=&87) ========================================================================== General description ------------------- Restarts the I/O processor of a remote machine after a Halt command (OSWORD A=&10 Control byte=&86). See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &87 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ Compatibility between Filing Systems ------------------------------------ Only supported by the NFS. The NFS need not be the current filing system. Identify Machine OSWORD A=&10 (Control byte=&88) ========================================================================== General description ------------------- This call interrogates a remote machine returning codes containing values to distinguish between manufacturers, machine types and software versions. See section 10.15 for information on polling the transmit for success. On entry -------- A=&10 YX point to the address of the control block shown below: 0 +-----------------------------+ | &88 | 1 +-----------------------------+ | 0 | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Pointer to start of local | | buffer | 8 +-----------------------------+ | Pointer to end of local | | buffer (start+4) | 12 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Modified | 1 +-----------------------------+ | Unchanged | 16 +-----------------------------+ The first four bytes of the buffer are relevant. The meaning of these bytes are shown below: Byte 1 This is defined by manufacturers and is intended to indicate the hardware design of the machine. The following are currently defined: Value Type of machine SJ Research FF Z80 CP/M FE SJ Research File Server FD RM480Z FC Nascom 2 (running CP/M) FB IBM Interface board FA SCSI Interface F9 SJ Research 80386 UNIX F8 SJ Research GP server Acorn 00 Reserved 01 BBC Microcomputer (OS 1 or 2) 02 Atom 03 System 3 or System 4 04 System 5 05 Master 128 (OS 3) 06 Electron 07 Archimedes (OS 6) 08 Reserved for future machine 09 Communicator 0A Master 128 ET 0B Filestore 0C Master Compact (OS 5) 0D EcoLink card for PCs 0F UNIX workstation 0F RISC PC 10 Iyonix 11 A9 40 ZX Spectrum 41 Amstrad CPC Other values Reserved Byte 2 This byte indicates the manufacturer. The following are currently defined: Value Manufacturer 00 Acorn 01 Torch 02 Reuters 40 J.G.Harston FF SJ Research Bytes 3 & 4 These contain the low and high bytes of the software release version in packed Binary Coded Decimal, byte 2 contains the version number and byte 4 the release. The easiest way to display packed BCD is to print it as if it were hexadecimal. Compatibility between Filing Systems ------------------------------------ Only supported by the Econet system. The NFS need not be the current filing system. 10.10 Set up Rx block OSWORD A=&11 ========================================================================== General description ------------------- This call is used to set up a receive block in your local machine. Once this has been done, data which is transmitted, or broadcast, on your port number, can be received. On entry -------- A=&11 YX point to the address of the control block shown below: 0 +-----------------------------+ | 0 | 1 +-----------------------------+ | &7F | 2 +-----------------------------+ | Port number | 3 +-----------------------------+ | Station number | 5 +-----------------------------+ | Pointer to start of buffer | 9 +-----------------------------+ | Pointer to end of buffer | 13 +-----------------------------+ If the port number is zero then the receive block will receive data transmitted on any port number. If the station number is zero then the receive block will receive data sent from any station, as long as the port number is correct. Note that the size of the buffer must be big enough to receive all the data transmitted otherwise the data will be rejected, and the receive block left open. To select the correct port number for your application see the Econet Standards Group paper 0001 at the end of this section. On exit ------- A,X,Y undefined 0 +-----------------------------+ | Receive block number | 1 +-----------------------------+ | Unchanged | 13 +-----------------------------+ If the receive block number allocated is zero then all the available receive blocks have been used. To correct this delete an unused receive block and retry the call. Issue 29 Apr 1987 10-32 SJresearch Read Rx block OSWORD A=&11 ========================================================================== General description ------------------- Once data has been received into an open receive block a read operation is needed to discover the source of the data and the number of bytes actually received. This call allows a copy of the updated control block to be written to the address pointed to by YX. Reading a receive block deletes the old receive block and allows that receive block to be reallocated. If the receive block was open to all stations, by using a station number of 0, then the actual machine number that sent the packet will be written; this is also the case for the port number. See section 10.15 for details of polling to see when data has arrived. On entry -------- A=&11 YX point to the address of the control block shown below: 0 +-----------------------------+ | Control block number | 1 +-----------------------------+ | Ignored | 13 +-----------------------------+ On exit ------- A,X,Y undefined 0 +-----------------------------+ | Control block number | 1 +-----------------------------+ | Control byte of tranmistted | | packet from remote station | 2 +-----------------------------+ | Port number of remote | | machine | 3 +-----------------------------+ | Station number of remote | | machine | 5 +-----------------------------+ | Pointer to start of data | 9 +-----------------------------+ | Pointer to end of data | 13 +-----------------------------+ 10.11 Read arguments OSWORD A=&12 ========================================================================== This call allows arguments to be read after a remote JSR (OSWORD A=&10 control byte=&83) and a user procedure call (OSWORD A=&10 control byte=&84). The remote machine will have the protect status bits set until this call is used, this is to prevent the arguments from being overwritten. The maximum size of the argument block is returned by OSWORD A=&13, function code=9. On entry -------- A=&12 YX point to the address in memory to put the arguments, of which the first two bytes are the source station number. On exit ------- A,X,Y undefined. Issue 29 Apr 1987 10-33 SJresearch 10.12 OSWORD A=&13 Call Summary ========================================================================== General description ------------------- These calls allow general local station information to be read and written. On entry -------- A=&13 YX point to the control block with the first byte determining the function and number of parameters. Except for function codes 0,1,6 and 7 the NFS does not need to be selected to perform the operations. Control byte Function 0 Read File Server number 1 Write File Server number 2 Read Printer Server number 3 Write Printer Server number 4 Read Protection mask 5 Write Protection mask 6 Read context handles 7 Write context handles 8 Read local station number 9 Read number, and size, of arguments 10 Read error number ANFS supports the following calls: 11 Read channel error occured on 12 Read Printer Server name 13 Write Printer Server name 14 Read space in NetPrint buffer 15 Read File Server retry delay 16 Write File Server retry delay 17 Translate net number On exit ------- A,X,Y undefined. Control block modified FS number OSWORD A=&13 (control byte=0/1) ========================================================================== General description ------------------- These calls allow the File Server number to be read and written. This value is used for all File Server commands including *I AM and OSWORD A=&14. To change onto a different File Server, context handles need to be written otherwise it is likely that any further operations will return the error 'Channel'. The ANFS utility '*FS' does both of these operations. The BBC NFS ROM defaults to the value 0.254 (i.e. station 254 on the local network). On the Master, Compact and Econet Terminal the default File Server number is held in CMOS RAM and is configured by the command '*CONFIGURE FS '. These calls should only be attempted with Econet selected as the current filing system. On entry -------- A=&13 YX point to the control block shown below: 0 +-----------------------------+ | Control byte | | 0 = Read FS number | | 1 = Write FS number | 1 +-----------------------------+ | File Server station | 3 +-----------------------------+ On exit ------- A,X,Y undefined For read operation the control block is modified as shown above. For write operation the control block is undefined. Issue 29 Apr 1987 10-34 SJresearch PS number OSWORD A=&13 (control byte=2/3) ========================================================================== General description ------------------- These calls concern the machine using a Print Server. To send a listing it is also necessary to set the printer type to the network, by issuing the command '*FX5,4'. The BBC NFS ROM defaults to the value 0.235 (i.e. station 235 on the local network). On the Master, Compact and Econet Terminal the default File Server number is held in CMOS RAM and is configured be the command ""CONFIGURE PS '. On entry -------- A=&13 YX point to the control block shown below: 0 +-----------------------------+ | Control byte | | 2 = Read FS number | | 3 = Write FS number | 1 +-----------------------------+ | Printer Server station | 3 +-----------------------------+ On exit ------- A,X,Y undefined For read operation the control block is modified as shown above. For write operation the control block is undefined. Protection mask OSWORD A=&13 (control byte=4/5) ========================================================================== General description ------------------- These calls allow the user to read and write the protection mask of the local machine. Note that if a remote machine attempts to do an operation requiring parameters returned then various protection bits will be set until the parameters have been read (using OSWORD A=&12). On entry -------- A=&13 YX point to the control block shown below: 0 +-----------------------------+ | Control byte | | 4 = Read protection mask | | 5 = Write protection mask | 1 +-----------------------------+ | Value of protection mask | 3 +-----------------------------+ If a bit of the protection mask is clear then the remote operation is allowed. The possible values of the protection mask are shown below: bit Operation 0 Peek 1 Poke 2 JSR 3 User procedure call 4 Operation system procedure call 5 Halt On exit ------- A,X,Y undefined For read operation the control block is modified as shown above. For write operation the control block is undefined. Issue 29 Apr 1987 10-35 SJresearch Context handles OSWORD A=&13 (control byte=6/7) ========================================================================== General description ------------------- Three directory handles describing the current environment are required for most File Server operations. These are returned by the File Server by the command '*I AM this net, then returns XY+3 unchanged On exit ------- A,X,Y undefined The control block is modified as above. Issue 01 Jul 1997 10-37 SJresearch 10.13 Send to FS OSWORD A=&14 (control byte=0) ========================================================================== General description ------------------- This call is used to communicate directly with the File Server and is detailed fully in the section detailing the File Server interface. The network must be the current filing system. On entry -------- A=&14 YX point to the control block shown below: 0 +----------------------------------+ | 0=Communicate with File Server | 1 +----------------------------------+ | Size of whole of block (x) | 2 +----------------------------------+ | 0 - NFS will put reply port here | 3 +----------------------------------+ | FS Function code | 4 +----------------------------------+ | 0 - NFS will put URD handle here | 5 +----------------------------------+ | 0 - NFS will put CSD handle here | 6 +----------------------------------+ | 0 - NFS will put LIB handle here | 7 +----------------------------------+ | Rest of FS transmit block | x +----------------------------------+ On exit ------- A,X,Y undefined Control block is modified as shown below: 0 +----------------------------------+ | 0 | 1 +----------------------------------+ | Size of rest of block | 2 +----------------------------------+ | Command code | 3 +----------------------------------+ | Return code | 4 +----------------------------------+ | Rest of file server recive block | x +----------------------------------+ Send text OSWORD A=&14 (control byte=1) ========================================================================== General description ------------------- This call sends a message to a remote machine and is used by the library utility *NOTIFY. The NFS must be the current filing system. On entry -------- A=&14 YX point to the control block show below: 0 +-----------------------------+ | 1 = Send text | 1 +-----------------------------+ | Destination station | 3 +-----------------------------+ | Text, terminated by 0 or 13 | x +-----------------------------+ On exit ------- A,X,Y undefined Contents of control block is undefined. The maximum size of text is 128 bytes when performed from a 2nd processor and 250 bytes when performed from the I/O processor. This call should not be used from within an interrupt routine. Issue 29 Apr 1987 10-38 SJresearch Cause remote error OSWORD A=&14 (control byte=2) ========================================================================== General description ------------------- This call causes a fatal error in a remote machine, by executing a BRK instruction followed by another 0, thus generating error 0. The NFS must be the current filing system. This is only guaranteed to be a fatal error in BASIC 2 and above. In BASIC 1 the ON ERROR will still trap fatal errors. Some other languages also incorrectly implement trapping of error 0. On entry -------- A=&14 YX point to the control block show below: 0 +-----------------------------+ | 2 = Cause fatal error | 1 +-----------------------------+ | Destination station | 3 +-----------------------------+ On exit ------- A,X,Y undefined Contents of control block is undefined. 10.14 OSBYTE Call Summary ========================================================================== Entry point &FFF4 Indirected via &20A On entry -------- A=Function code Value in A Function A=&32 Poll transmit block A=&33 Poll receive block A=&34 Delete a receive block A=&35 Sever remote connection On exit ------- X=Result dependent on the function A,Y,C undefined Issue 29 Apr 1987 10-39 SJresearch Poll Transmit OSBYTE A=&32 ========================================================================== General description ------------------- This call is used to poll a transmit operation for completion. If an error occured the error code will be returned in X. On entry -------- A=&32 On exit ------- X=0 if the transmission has been completed successfully, otherwise the following bits in X are relevant. Bit 7 is the top bit, bit 0 is the bottom bit. bit state Meaning 7 0 completed 1 in progress 6 0 sucessful 1 failed 5 0 4 0 3 0 2-0 hold the error code Error codes 0 Line jammed 1 Incomplete or bad four-way handshake (Net error) 2 No acknowledge to scout packet (Not listening) 3 No clock 4 Bad transmit control block A,Y,C undefined Example ------- DEF FNpoll_Tx LOCAL Result%,A% A%=&32 REPEAT Result%=(USR(osbyte) AND &FF00) DIV &100) UNTIL Result%<&80 =Result% The BASIC function above will poll the last transmit operation until it has been completed. When the function returns, if the result is non-zero, then there has been an error in the transmission and the transmit command may have to be redone. Poll Receive OSBYTE A=&33 ========================================================================== General description ------------------- This call is used to check whether anything has been received in a receive block. On entry -------- A=&33 X=control block number On exit ------- X has the top bit set if a message has been received. A,Y undefined C undefined Example ------- DEF FNpoll_Rx(X%) LOCAL Result%,A% A%=&33 =((USRosbyte AND &8000)<>0) The above example, when given a control block number as a parameter, will return -1 (TRUE) if anything has been received. 10 CB%=FNset_up_Rx :REM Your function which sets up a receive block 20 :REM and returns the control block number. 30 REPEAT 40 UNTIL FNpoll_Rx(CB%) 50 PRINT'Something has been received! Issue 29 Apr 1987 10-40 SJresearch Delete receive block OSBYTE A=&34 ========================================================================== General description ------------------- This call is used to delete a receive block. On entry -------- A=&34 X=control block number On exit ------- X control block number A,Y undefined C undefined 10.15 Transmitting ========================================================================== To transmit a packet over the network using the BBC microcomputer it is necessary to set up a control block in memory. A transmit control block will always take the form: 0 +-----------------------------+ | Control byte (top bit set) | 1 +-----------------------------+ | Port | 2 +-----------------------------+ | Remote station | | (station number, network) | 4 +-----------------------------+ | Start of data | 8 +-----------------------------+ | End of data | 12 +-----------------------------+ | Remote start of data | 16 +-----------------------------+ The control byte always has the top bit set. The rest of the byte is called a control code which, with the exception of immediate operations, makes no difference what value is chosen. Check that the port number is within the correct range for your application by checking it against the Econet Standards Group paper 0001. General procedure for transmitting ---------------------------------- 1) Set up the control block and the number of retries to perform. 2) Store the control byte in the control block. 3) Set the accumulator to &10 and YX to point to the control block. 4) CALL OSWORD to perform the call 5) Read the control byte of the control block. If this is zero then the transmission has failed to start so go to step 2. 6) Poll for completion (Using OSBYTE A=&32). 7) If not completed (i.e. top bit of X register still set) go to step 6. 8) Has transmission worked (Using OSBYTE A=&32 to find whether X is 0). 9) If there was a non-fatal error in the transmission then decrement the number of retries and if the number of retries is greater than 0 go to step 2. 10) If the error was fatal or the number of retries=0 then finish otherwise return. The terms fatal and non-fatal refer to the type of error returned by OSBYTE with A=&32. The errors 'line jammed' (&40), 'no clock' (&43) and 'bad transmit control block' (&44) are all fatal: this is because they all need manual intervention by the user to cure them, a detailed explanation of these errors is given in appendix A. Issue 29 Apr 1987 10-40 SJresearch The errors 'four way handshake damaged' (&41) and 'no scout adenowlegement' (&42) are termed non-fatal The error 'no scout acknowlegement' is normally caused by either, the remote machine having no receive block open to receive the data, the machine has the protection status set or the machine is not on the network. The error 'four way handshake damaged' is normally caused by the receive buffer size of the remote machine not being big enough, the data colliding with someone else transmitting or electrical interference. It should be noted that the Acorn BBC B+ and early Master series microcomputers do not have any collision detect hardware (although it can be fitted) and so it is possible that it may not always transmit correctly, especially on the broadcast operation. Broadcasting ------------ This is a special version of the transmit operation. It allows a station to simultaneously send eight bytes of data to every other station on every network, that has a receive block open and is currently the only method of communicating with the bridge. However, the call has no handshaking so it is not possible to guarantee that the remote stations received the data. The control block is shown below: 0 +-----------------------------+ | Control byte (top bit set) | 1 +-----------------------------+ | Port | 2 +-----------------------------+ | &FFFF | 4 +-----------------------------+ | Data | 12 +-----------------------------+ If the remote station has a receive block open on the correct port number then the data will be received like a normal transmit, except that if the remote station has NFS version 3.34 the data will be written over the pointers of the receive control block instead of the location pointed to. Transmitting under Interrupts ----------------------------- If an application requires performing a transmission under interrupts then there is a special precaution to take. This is because the transmit routine interrupts and so there is the possibility that a transmission under interrupts may occur whilst a transmission is already taking place. Thus polling the transmit will get the result of the last transmission. To get around this problem the following must be done: Before transmitting save the old transmission poll flag by: .loop LDY #&6F LDA (&9C),Y BMI loop PHA Having successfully transmitted, restore the old transmission poll flag by: LDY #&6F PLA STA (&9C),Y It is essential that the above routines are executed in the I/O processor. 10.16 Receiving ========================================================================== A receive block is needed to receive a transmission from a remote machine. The only exceptions to this are the immediate operations, these are handled specially by the NFS ROM. Before a receive block can be used it must be set up. This is performed by setting up a control block and CALLing OSWORD A=&11. If a valid receive block number is returned then the receive block is open. The receive block will only be filled if all the following conditions are met: 1) The correct station replies 2) The data is sent on the correct port number 3) The amount of data sent is not bigger than the buffer size reserved. Events on reception ------------------- The ANFS ROM can produce an event on reception of data into a receive block. Events are enabled using *FX 52,150,0. Events are disabled using *FX 52,100,0. The event number is 254 and on entry Y holds the control block number of the receive block which received data. Issue 29 Apr 1987 10-42 SJresearch 10.17 Port numbers ========================================================================== The information below is a copy of a paper by the Econet Standards Group. ESG paper 0001 -------------- This standard defines the way in which port number may legally be used. They should only be used for the purposes given in the following list. 00 Illegal (note 1) 01-0F Reply only (note 2) 10-2F Torch Computers (note 3) 30-8F Reserved for future allocation 90-9F Acorn Computers (note 3) A0-AF SJ Research (note 3) B0-B1 Server logon protocol (note 2) B2-CF Reserved for future allocation D0-DF Acorn Computers (note 3) E0-FE User Programs FF Ilegal Notes ----- 1) Used to provide immediate operations. 2) These ports may be used by anyone for any purpose, subject to certain restrictions. They may not be used to initiate a new protocol, but may be used to receive replies within a protocol initiated using some other port. When receiving data on these ports, the receive block must be open for a specific station, and not for all stations. Data should never be sent on these ports unless it is certain that the recipient is prepared for that data, and is carrying out the same protocol. Broadcasts may not be sent on these ports. These ports must only be used by software which has complete control of one end of the connection, and can ensure that no other software will attempt to transmit or receive on these ports at the same time. It is suggested that unsolicited traffic on these ports be discarded immediately by any software that receives it 3) Where numbers are allocated to a particular organisation, that organisation will control the use of those numbers. However, it is to be hoped that, as new standards are agreed, some or all of these numbers will be allocated to specific purposes at a later date. Currently used ports -------------------- Ports which are currently used are: 54 DigitalServicesTapeStore 93 Remote 99 FileServerCommand 9C Bridge 9E PrinterServerlnquiryReply 9F PrinterServerlnquiry A0 SJ Research *FAST protocol AF SJ Research Nexus net find reply port B0 FindServer B1 FindServerReply B2 TeletextServerCommand B3 TeletextServerPage D0 PrinterServerReply D1 PrinterServerData D2 TCPIPProtocolSuite D3 SIDFrameSlave D4 Scrollarama D5 Phone D6 BroadcastControl D7 BroadcastData D8 ImpressionLicenceChecker D9 DigitalServicesSquirrel DA SIDSecondary DB DigitalServicesSquirrel2 DC DataDistributionControl DD DataDistributionData DE ClassROM DF PrinterSpoolerCommand 10.18 The Bridge ========================================================================== The number of stations on any one network is limited to 254, because the station number is a one byte number and values 255 and 0 are reserved for special purposes. An Acorn bridge is used 10 connect two Econet networks together; bridges can be used to connect up to 127 networks together, giving a maximum of 32258 stations in total. Another use of a bridge is to split a long network so that the data transfer rate inside a network can be fast. This is because each network will be shorter; only when data is being transferred between networks does the data transfer rate slow down. If a fault appears on one of the networks then the other network will continue to work; this is particularly useful for developing and testing new Econet hardware. The last use of a bridge is to allow otherwise illegal network layouts, the most common of these being a T junction How to use the bridge --------------------- All the,primitives supplied by the NFS ROM have two bytes reserved for the station number. The first byte is the station number and the second byte is the network number. To communicate with machines on the local network the network number should be 0. For a station on network 4 to communicate with another station on network 4, the network number would be 0. For a station on network 5 to communicate with a station on network 4, the network number would be 4 When the bridge is not transferring data, it looks at all the scout packets being sent on both of the networks that it is bridging across, called the networks adjacent to the bridge. If the scout packet contains a network number which is within reach through the bridge, then the bridge will perform a four-way handshake between the networks to transfer the data. To do a four way handshake the bridge receives data from one adjacent network and puts it into its own RAM. While this is done, the bridge sends flags on the other adjacent line to prevent any network activity. Once the transfer of data has been completed, the bridge moves to flagging the first network instead, while it transfers the data from its internal RAM onto the