RISCOS.com
www.riscos.com Technical Support:
Programmer's Reference Manual

File server protocol interface

The user environment

Handles

A client is identified and authenticated to the file server by its station number and three handles. When a user logs on the file server creates these handles by opening directories; the handles identify to the file server the environment in which to interpret commands and to look up filenames presented by the client. The file server closes the handles when the user logs off again. The three handles which comprise the user environment are the currently selected directory or CSD (see @ is the currently selected directory (CSD) and *Dir), the user root directory or URD (see & is the user root directory (URD) and *URD), and the library directory or Lib (see % is the currently selected library directory (CSL) and *Lib). Incidentally, the handles passed to the client are only used for the client/server communication, and are not the file server's own file handles for the directories.

Usually the client machine's software deals with the manipulation of these handles, but you can define your own environment by opening several directories and declaring a set of these handles as representing the current environment. Thus you can execute commands in a number of different environments.

Protocol Block Formats

Standard Tx Header

The initial protocol blocks that the client sends to the file server take a standard form. This form is known as the standard Tx header:

Byte	Meaning
1	reply port
2	function code
3	handle for user root directory (URD)
4	handle for currently selected directory (CSD)
5	handle for library directory (Lib)

The reply port is the Econet port on which the client station is prepared to receive a response from the file server. The function code indicates to the file server which operation to perform; for a list of available function codes, see the chapter entitled File Server Function Codes. The three handles define the environment for the command, as described above. The command is sent to the file server on port &99, which is known as the command port.

Standard Rx Header

The responses that the file server returns to the client also take a standard form, known as the standard Rx header:

Byte	Meaning
1	command code
2	return code

The command code indicates to the client what action (if any) the client should take upon receiving this response. The command code is principally used when responding to a 'Decode command line' function (see Decode command line). The return code gives the status of the command passed to the file server:

Zero indicates that the command step completed successfully
Non-zero values are an error number indicating what error has occurred; the remainder of the message contains an ASCII string describing the error, which is terminated by a carriage return.

Standard Data Types

The file server protocols use standard data types for most operations.

Multi-byte values

In all cases multi-byte values are stored low byte first.

Object and user names

All specifications of object and user names may be 8-bit values, save that &80 is reserved since it is used to indicate the end of data in some file server protocols.

File size

File servers only support files up to 16 Megabytes, so all pointer operations and file length indications use 24 bit quantities (stored low byte first, of course). Econet protocols do not support larger files.

Attributes

The attributes for an object are stored in a single byte with the bit set to '1' meaning as follows:

Bit	Meaning if set
0	object has public read access
1	object has public write access
2	object has owner read access
3	object has owner write access
4	object is locked against owner deletion
5	object is a directory
6	object is a protected directory

Note that public lock is always implicitly set.

Date

The date is stored in two bytes thus:

File server protocol date format

As you can see, the year is encoded as a seven bit number (ie 0 - 127); this is used to specify the offset from 1981.

Access rights

The access rights to a directory are encoded in a single byte:

Value	Meaning
0	owner access
&FF	public access

Object type

The object type is encoded in a single byte:

Value	Meaning
0	object not found
1	object is a file
2	object is a directory
3	object is an image file (ie both file and directory)

Privilege

A client may have different levels of privilege. The values for each privilege level are as follows:

Value	Meaning	Character equivalent
&00	locked	L
&40	fixed	F
&80	normal
&FF	system manager	S

The character equivalents are used by some command line interfaces.

Object names

Object names are currently limited by the filing system, usually 10 characters. They may contain 8 bit values and are not case sensitive.

User identifiers

User identifiers are normally 10 characters with a provision for group identifiers ie: group.name, each of 10 characters.

Disc titles

The disc title is the name that the server exports to network clients. The length is determined by the host file system however it must start with a letter and consists of alphanumeric characters (ie: A-Z, a-z, 0-9), "-" and "_".

Passwords

The password file associated with the server holds encrypted passwords, privilege levels, boot options and space allocation information for each user.

File Server Function Codes

A summary of the file server function codes is given below. Function is the function code number, Privilege shows whether the client has to have privilege, and Logged-on shows whether the client has to be logged-on:

Function	Privilege	Logged-on	Description
0	no	yes †	Decode command line
1	no	yes	Save file
2	no	yes	Load file
3	no	yes	Examine
4	no	yes	Catalogue header
5	no	yes	Load as
6	no	yes	Open object
7	no	yes	Close object
8	no	yes	Get byte
9	no	yes	Put byte
10	no	yes	Get bytes
11	no	yes	Put bytes
12	no	yes	Read random access arguments
13	no	yes	Set random access arguments
14	no	no	Read disc information
15	no	yes	Read current users' information
16	no	no	Read file server date and time
17	no	yes	Read 'End-of-file' status
18	no	yes	Read object information
19	no	yes	Set object attributes
20	no	yes	Delete object
21	no	yes	Read user environment
22	no	yes	Set user boot option
23	no	yes	Log off
24	no	yes	Read user's information
25	no	no	Read file server version number
26	no	yes	Read disc free space information
27	no	yes	Create directory, specifying size
28	yes	yes	Set file server date and time
29	no	yes	Create file
30	no	yes	Read user free space
31	yes	yes	Set user free space
32	no	yes	Read client UserId
33	no	yes	Read current users' info (extended)
34	no	yes	Read user's information (extended)
35	reserved
36	yes	yes	Manager interface
37	reserved

† There is no need to be logged-on to decode the *I Am command.

Interfaces

This section deals individually with each of the commands and functions available to client software. The exchange of packets is detailed and the format of requests and responses is given.

Decode command line

A number of the operations performed by the file server are initiated by the sending of a command line.

The command line syntaxes which the Acorn File Server will accept are as follows (commands in bold are new Level 4 commands):

*Access object_spec [attributes]
*Bye<
*CDir directory
*Delete object
*Dir [directory]
*I am user_name [password]
*Info object_spec
*Lib [directory]
*Logon user_name [password]
*Pass old_password new_password
*Rename object new_name
*SDisc [:]disc_spec

Management specific commands:

*FSShutdown
*Logoff user_name|user_number
*NewUser user_name
*Priv user_name [new_privilege]
*RemUser user_name

The syntax of some of the above commands differ from the equivalent RISC OS commands, because the command line will already have been processed before the command is issued to the file server.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 0)
6...	command line, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3...	command dependent results

The possible command codes in the standard Rx header that the file server may return are:

Code	Meaning
0	no further action needed (ie command complete)
1	reserved
2	reserved
3	reserved
4	*Info
5	*I Am
6	*SDisc
7	*Dir
8	unrecognised command
9	*Lib
10	disc information, function code 14 called
11	users information, function code 15 called

Some commands require further action by the client, in which case the file server will also return (in byte 3 onwards) any decoded parameters or data which the client will need to complete the command:

Return from *Info

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 4)
3 - 12	object name, padded with spaces
13	space
14 - 21	load address, padded with zeros
22	space
23 - 30	execution address, padded with zeros
31 - 33	spaces
34 - 39	length padded with zeros
40 - 42	spaces
43 - 48	access details (eg LWR/WR), padded with spaces
49 - 53	spaces
54 - 61	date (DD:MM:YY)
62	space
63 - 68	System Internal Name (SIN), padded with zeros
69	terminating negative byte (&80)

'Spaces' are ASCII spaces (&20). 'Zeros' are ASCII zeros (&30), not null bytes (&00).

Return from *I Am

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 5)
3	new URD handle
4	new CSD handle
5	new Lib handle
6	boot option (bits 0 - 3 significant)

Return from *SDisc

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 6)
3	new URD handle
4	new CSD handle
5	new Lib handle

Return from *Dir

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 7)
3	new CSD handle

Return from unrecognised command

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 8)
3...	command string, terminated by CR

Return from *Lib

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 9)
3	new Lib handle

Save file

This is the actual save operation. This protocol is used after the command line has been decoded, either by the file server or the local operating system.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1	reply port
2	1 (function code)
3	acknowledge port
4	CSD handle
5	Lib handle
6 - 9	file load address
10 - 13	file execute address
14 - 16	file size
17...	file name, terminated by CR

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header (command code = 3 if leaf name is returned, otherwise = 0)
3	data port
4 - 5	maximum data block size
6...	leaf name, terminated by CR (if returned)

The client and file server now enter the 'data transfer' phase of the protocol where the file server acknowledges the receipt of each data packet. If there is no data to be sent (eg a zero length file) then this phase is omitted. If the file server detects an error during the data transfer phase (eg a disc error) then the phase is allowed to complete, but the Save file operation is aborted, and the error status is given in the return code of the 'final acknowledge' (see below).

The client sends each block of data to the file server's data port, as specified in the file server's initial reply (see above):

Byte	Meaning
1...	a block of data, up to the maximum data block size

The file server acknowledges the receipt of each block by sending to the client's acknowledge port, as specified by the client in its initial transmission (see above):

Byte	Meaning
1	a single byte of undefined value

When the file server receives the final data block it instead acknowledges it with the 'final acknowledge', which is the terminating packet of the protocol. It sends this to the client's reply port, which - again - was specified in the client's initial packet:

Byte	Meaning
1 - 2	standard Rx header
3	attributes
4 - 5	date

Load file

This is the actual load operation. This protocol is used after the command line has been decoded, either by the file server or the local operating system.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1	reply port
2	2 (function code)
3	data port
4	CSD handle
5	Lib handle
6...	file name, terminated by CR - may be wildcarded

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header (command code = 14 if leaf name is resolved, otherwise = 0)
3 - 6	file load address
7 - 10	file execute address
11 - 13	file size
14	file access
15 - 16	file creation date
17...	leaf name, terminated by CR, with wild-cards resolved (if returned)

The client and file server now enter the 'data transfer' phase of the protocol. If the file is of zero length then this phase is omitted. If the file server detects an error (eg a disc error) then the required amount of data will be sent, but its data content is undefined.

The file server sends each block of data to the client's data port, as specified in the client's initial packet:

Byte	Meaning
1...	data blocks of undefined size repeated until 'file size' data has been sent (maximum data block size is currently 4k)

The client does not acknowledge these packets.

When the file server has sent the final data block it then sends the terminating packet of the protocol to the client's reply port, which - again - was specified in the client's initial packet:

Byte	Meaning
1 - 2	standard Rx header

Examine

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 3)
6	argument to examine function: 0 return all information, in machine readable format 1 return all information, in character string format 2 return file title only, in machine readable format 3 return file title and access, in character string format
7	directory entry point (0 - 255)
8	number of entries to examine (1 - 255, or 0 for all)
9...	name of directory to be examined, terminated by CR

The argument passed in byte 6 specifies the format and amount of information to be returned by the file server.

The directory entry point gives the entry number within the directory from which to examine. Conventionally the first entry in a directory is entry number zero.

The number of entries to examine specifies how many entries are to be examined, so is usually determined by the buffer space available to the client. A parameter of zero in this case conventionally demands that all entries in the directory from the entry point to the end of the directory be examined.

Information may be returned in two ways: as a character string, or in a machine readable format:

Information that is returned in character string format is in a fixed format - including separators - that is suitable for direct output. Carriage returns may occur within such strings. Individual directory entries are delimited by zero bytes (&00), the final entry being terminated by a negative byte (&80).
Information that is returned in machine readable format consists of a defined number of bytes, and so there are no delimiters between entries, although the final entry is still terminated by a negative byte (&80).

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header
3	number of entries actually examined
4	number of entries in directory
5...	argument dependent information

The different formats of byte 5 onwards are given below.

Return for all information in machine readable format (argument = 0)

Byte	Meaning
5 - 14	object name padded to 10 characters with spaces
15 - 18	load address
19 - 22	execute address
23	attributes
24 - 25	date
26 - 28	System Internal Name (SIN)
29 - 31	object length

Return for all information in character string format (argument = 1)

Byte	Meaning
5...	character string of all information data (see above for character string format/separators)

Return for file title only, in machine readable format (argument = 2)

Byte	Meaning
5	10 (object name length for BBC MOS)
6...	object name padded with spaces

Return for file title and access, in character string format (argument = 3)

Byte	Meaning
5...	character string giving object name and formatted access string (see above for character string format/separators)

Catalogue Header

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 4)
6...	directory name, terminated by CR (null name catalogue CSD)

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header
3 - 13	last component of directory name padded with spaces
14	character indicating ownership of directory ('O' or 'P')
15 - 17	three space characters (&20)
18 - 33	current disc name padded with spaces, terminated by CR, negative byte (&80)

Load as

This is exactly the same as Load file (Function code = 2), except that the file name is looked up in the CSD and then in the Lib. The error returned if the file name is not found in either directory is 'Bad command'.

The protocol is identical, save that the client's initial packet has a function code of 5 (for 'Load as') rather than 2 (for 'Load file').

Open object

This function code creates a handle for the object specified with the access type requested. Such handles are used for performing random access operations, and also for manipulating the user's environment. An object will be opened only if the client has the necessary access rights to the object. When opening directories these must be specified as already existing. A file can be opened several times for reading, but only once for update. A file will be created with default size of &400 bytes if it does not already exist, and is opened for update, and the client specifies a new file (byte 6 = 0). Machine-dependent limits are imposed on the number of handles a client is allowed to have open at any one time. BBC machines support 8, Master series and Archimedes clients are allowed 16. These values include 3 handles which are automatically allocated when the client logs on, therefore a BBC machine will be able to open a further 5 objects.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 6)
6	zero create a new file, deleting existing data non-zero object must already exist
7	zero open object for update non-zero open object for reading only
8...	object name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header (command code = 1 if leafname is returned, otherwise = 0)
3	object's handle
4...	leaf name, terminated by CR (if returned)

Close object

This function indicates to the file server that the handle passed as argument is no longer needed and that all of the updated data in the file should be written out to the disc. A handle of zero indicates to the file server that all handles to open files are to be closed. This call does not close handles to directories if the handle given is zero.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 7)
6	handle

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Get byte

The next four function codes deal with the facilities that the file server provides to enable the user to perform random access operations on open files.

These operations have an additional protocol to ensure the integrity of the data exchanged, provided by a sequence number. The sequence number is a single bit held in both client and file server which differentiates between:

successive reads of a file using the pointer held in the file server
repeated reads of the same byte, because the operation failed at the previous attempt.

The client sends the sequence number in the least significant bit of the flag byte of the Econet control block. The file server returns its copy of the sequence number with the data to allow the client to detect data sequencing errors. The client should invert its copy of the sequence number after every successful transaction with the file server. If the client detects a data packet with the incorrect sequence number, then the client should be prepared to repeat the request.

The Get byte function code reads a single byte from the file at the position specified by the file server's internal file pointer. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1	reply port
2	8 (function code)
3	file handle

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header
3	byte read (&FE if reading first byte after file end)
4	&00 normal read operation
	&80 last byte in the file
	&C0 FIRST BYTE AFTER FILE END

Put byte

This function code writes a single byte to the file at the position specified by the file server's internal file pointer. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1	reply port
2	9 (function code)
3	file handle
4	byte to be written

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header

Get bytes

This operation allows the client to read blocks of data. The client may supply an offset within the file at which to start the operation, or may use the sequential file pointer maintained by the file server. The protocol includes a sequence number as described for Get byte and Put byte. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1	reply port
2	10 (function code)
3	data port
4	CSD handle
5	Lib handle
6	file handle
7	zero use supplied offset
	non-zero use file server sequential pointer
8 - 10	number of bytes to transfer
11 - 13	file offset (ignored if byte 7 non-zero)

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header

The client and file server now enter the 'data transfer' phase of the protocol. If the transfer is of zero length then this phase is omitted. If the file server detects an error (eg a disc error) then the required amount of data will be sent, but its data content is undefined. If a read extends over the end of the file then the requested amount of data will be returned, but the data content of the bytes beyond the end of the file is undefined.

The file server sends each block of data to the client's data port, as specified in the client's initial packet:

Byte	Meaning
1...	data blocks of undefined size repeated until 'transfer size' data has been sent (maximum data block size is currently 4k)

The client does not acknowledge these packets.

When the file server has sent the final data block it then sends the terminating packet of the protocol to the client's reply port, which - again - was specified in the client's initial packet:

Byte	Meaning
1 - 2	standard Rx header
3	&00 all OK
	&80 read includes last byte in file
4 - 6	number of valid data bytes transferred

Put bytes

This operation allows the client to write blocks of data. The client may supply an offset within the file at which to start the operation, or may use the sequential file pointer maintained by the file server. The protocol includes a sequence number as described for Get byte and Put byte. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1	reply port
2	11 (function code)
3	acknowledge port
4	CSD handle
5	Lib handle
6	file handle
7	zero use supplied offset non-zero use file server sequential pointer
8 - 10	number of bytes to transfer
11 - 13	file offset (if supplied)

The file server's reply is sent to the client's reply port, as specified in the client's initial packet (see above):

Byte	Meaning
1 - 2	standard Rx header
3	data port
4 - 5	maximum data block size

The client and file server now enter the 'data transfer' phase of the protocol where the file server acknowledges the receipt of each data packet. If there is no data to be sent then this phase is omitted. If the file server detects an error during the data transfer phase (eg a disc error) then the phase is allowed to complete, but the operation is aborted, and the error status is returned in the return code of the 'final acknowledge' (see below).

The client sends each block of data to the file server's data port, as specified in the file server's initial reply (see above):

Byte	Meaning
1...	a block of data, up to the maximum data block size

The file server acknowledges the receipt of each block by sending to the client's acknowledge port, as specified by the client in its initial transmission (see above):

Byte	Meaning
1	a single byte of undefined value

Byte	Meaning
1 - 2	standard Rx header
3	undefined
4 - 6	number of valid data bytes transferred

Read random access information

This function code allows the client to discover information about files for which he currently has handles. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 12)
6	file handle
7	0 read sequential file pointer 1 read file extent (the amount of valid data) 2 read file size (the space allocated for the file)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 5	information requested

Set random access information

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 13)
6	file handle
7	0 set sequential file pointer 1 set file extent
8 - 10	value to set

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Read disc information

This function returns the disc configuration of the file server. Conventionally the file server's drives are logically numbered from zero upwards. However, this number is not the same as the drive number returned, which is the physical drive number. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 14)
6	first logical drive number to interrogate
7	number of drives to interrogate (0 for all drives)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	number of drives found
4	physical drive number of first drive requested
5 - 20	disc name of first drive requested, padded with spaces
21...	further 17-byte entries in same format

Read current users' information

This function returns the currently logged on users of the file server, their station numbers and associated privileges. Conventionally the logged on user entries are numbered from zero. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 15)
6	first entry for which to get information
7	number of entries for which to get information (0 for all)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	number of entries returned
4	station number of first user	repeated for each entry returned
5	network number of first user
6...	name of first user, terminated by CR
n	privilege of first user

Read file server date and time

It is not necessary to be logged on to the file server to use this function code. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 16)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 4	date
5	hours (0 - 23)
6	minutes (0 - 59)
7	seconds (0 - 59)

Read 'End-of-file' status

This function is valid for file handles only. The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 17)
6	file handle

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	zero pointer within file non-zero POINTER OUTSIDE FILE

Read object information

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 18)
6	1 read object creation date 2 read load and execute address 3 read object length 4 read object attributes and access rights 5 read all object information 6 read access rights and cycle number of directory 7 read unique identifier
7...	object name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header). The reply's contents depend on the argument passed with the call:

Reply to arguments 1 - 5

Byte	Meaning
1 - 2	standard Rx header
3	object type
4...	requested results only, returned in the following order:
	load address (4 bytes), execute address (4 bytes),
	length (3 bytes), attributes (1 byte), date (2 bytes),
	access rights (1 byte)

Reply to argument 6

Byte	Meaning
1 - 2	standard Rx header
3	undefined
4	0
5	10(length of directory name)
6 - 15	directory name padded with spaces
16	access rights
17	number of entries in directory

Reply to argument 7

Byte	Meaning
1 - 2	standard Rx header
3	object type
4 - 9	unique identifier for that object on that server (SIN + disc number):
	bits 0 - 23	file system System Identification Number (SIN)
	bits 24 - 31	file server disc number
	bits 32 - 47	filing system number

Set object attributes

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 19)
6	1 SET LOAD ADDRESS_ EXECUTE ADDRESS_ AND attributes 2 set load address 3 set execute address 4 set attributes 5 SET CREATION date
7...	parameters to set (depend on byte 6)
n...	file name, terminated by CR
The lengths of the parameters to set are the same as the lengths of the parameters returned by Read object information: see Read object information.

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Delete object

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 20)
6...	object name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 6	load address
7 - 10	execute address
11 - 13	file length
14	file attributes

Read user environment

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 21)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	16 (length of disc name)
4 - 19	name of currently selected disc, padded with spaces
20 - 29	name of CSD, padded with spaces
30 - 39	name of Lib, padded with spaces

Set user boot option

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 22)
6	new boot option (bits 0 - 3 significant)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Log off

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 23)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Read single user's information

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 24)
6...	user name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	user's privilege
4	user's station number
5	user's network number

Read file server version number

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 25)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 11	a text string describing the file server type
12	a space character (ASCII &20)
13 - 16	a text string of the form n.xy which is the version

Read disc free space

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 26)
6...	disc name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 5	free space on disc (in sectors of &100 bytes)
6 - 8	disc size (in sectors of &100 bytes)

Create directory, specifying size

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 27)
6	maximum number of sectors to allocate
7...	name of directory, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Set file server date and time

It is necessary to be logged on to the file server, with privilege, to set the date and time parameters.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 28)
6 - 7	date
8	hours (0 - 23)
9	minutes (0 - 59)
10	seconds (0 - 59)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Create file

This function creates a file of the size and type specified. The contents will automatically be set to zeros for security reasons.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 29)
6 - 9	new file's load address
10 - 13	new file's execute address
14 - 16	new file's length
17...	new file's name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	new file's attributes
4 - 5	new file's creation date

Read user free space

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 30)
6...	UserId for free space reading, terminated by CR; CR alone means return the free space of the client

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 6	available space for UserId, in bytes

Set user free space

This function code is only legal for privileged users. The UserId specified is that of the client whose space allocation is to be amended.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 31)
6 - 9	new value for available space, in bytes
10...	UserId, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Read client UserId

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 32)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3...	UserId of client, terminated by CR

Read current users' information (extended)

Byte	Meaning
1 - 5	standard Tx header (function code = 33)
6	first entry for which to get information
7	number of entries for which to get information (0 for all)

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	number of entries returned
4	station number of first user	repeated for each entry returned
5	network number of first user
6	task number of first user
7...	name of first user, terminated by CR
n	privilege of first user

Read single user's information (extended)

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header (function code = 34)
6...	user name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3	user's privilege
4	user's station number
5	user's network number
6	user's task number

Manager Interface

This function allows the system manager to manipulate all the details concerning the users of the system. The password file will then be updated accordingly.

You must be a privileged user to use this function.

The client initiates the exchange by sending to the file server's command port:

Byte	Meaning
1 - 5	standard Tx header, Function code = 36 (&24)
6	argument: 0 read number of entries in password file 1 read entry from password file 2 write user profile in password file 3 add new user 4 remove user 5 set privilege 6 logoff user 7 shutdown server
7...	argument dependent parameters (see below)

The argument passed in byte 6 specifies the function to be performed by the file server. Some of these functions require further parameters, which are given in byte 7 onwards of this initial protocol block. These are detailed below.

Read number of entries in password file (argument = 0)

No argument dependent parameters are passed with the initial protocol block.

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 6	number of users

Read entry from password file (argument = 1)

The argument dependent parameters passed with the initial protocol block are:

Byte	Meaning
7 - 8	user number for which to get information

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header
3 - 6	user profile index
7	privilege
8	boot option (bits 0 - 3 significant)
9 - 12	spaces
13	station (if client logged on)
14	net (if client logged on)
15	allowed to log on flag (bit 1 significant)
16 - 37	user name, terminated by CR
38 - 60	password, terminated by CR
61...	URD name, terminated by CR

Write user profile in password file (argument = 2)

The argument dependent parameters passed with the initial protocol block are:

Byte	Meaning
7 - 10	reserved (must be zero)
11	privilege
12	boot option (bits 0 - 3 significant)
13 - 18	spaces
19	allowed to log on flag (bit 1 significant)
20 - 41	user name, terminated by CR
42 - 64	password, terminated by CR
65...	URD name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Add new user (argument = 3)

The argument dependent parameters passed with the initial protocol block are:

Byte	Meaning
7	user name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Remove user (argument = 4)

The argument dependent parameters passed with the initial protocol block are:

Byte	Meaning
7	user name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Set privilege (argument = 5)

The argument dependent parameters passed with the initial protocol block are:

Byte	Meaning
7	user name, terminated by CR
n...	new privilege ('S', 'L' or 'F'; or null for normal), terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Logoff user (argument = 6)

The argument dependent parameters passed with the initial protocol block are:

Byte	Meaning
7	user name, terminated by CR

The file server's reply is sent to the client's reply port, as specified by the client in its standard Tx header (see Standard Tx Header):

Byte	Meaning
1 - 2	standard Rx header

Shutdown server (argument = 7)

No argument dependent parameters are passed with the initial protocol block.

Error messages

The server responds with errors under certain circumstances. The errors generated are as follows:

Network reported errors

Error string	Error Number
Insufficient space	&5C
Too much data	&83
Bad privilege letter	&8C
Bad user name	&AC
Bad rename	&B0
Already a user	&B1
Directory full	&B3
Is a directory	&B5
Too many users	&B8
Password must be between 6 and 22 characters	&B9
Insufficient privilege	&BA
Wrong password	&BB
User not known	&BC
Access violation	&BD
Insufficient access	&BD
Is a file	&BD
Who are you?	&BF
Too many open files	&C0
Already open	&C2
Disc full	&C6
Bad name	&CC
Bad directory name	&CC
Bad drive	&CD
Invalid access string	&CF
Not found	&D6
File not found	&D6
Channel	&DE
Sorry, not supported	&FD
Bad command	&FE
Server not available	&FF
Server has shut down	&FF
No more receive buffers	&FF
Failed to create user profile	&FF
Server internal error, please report to system manager	&FF

Errors in bold are new Level 4 errors.

Internal errors

Unable to open password file
No devices found, unable to start ...
Unable to open/find choices file
Unable to find floppy disc
Unable to mount ...
Unable to execute ...
Error in exports file, unable to start
Unable to find exports file

	www.riscos.com Technical Support: Programmer's Reference Manual

www.riscos.com Technical Support:Programmer's Reference Manual

File server protocol interface

The user environment

Handles

Protocol Block Formats

Standard Tx Header

Standard Rx Header

Standard Data Types

Multi-byte values

Object and user names

File size

Attributes

Date

Access rights

Object type

Privilege

Object names

User identifiers

Disc titles

Passwords

File Server Function Codes

Interfaces

Decode command line

Return from *Info

Return from *I Am

Return from *SDisc

Return from *Dir

Return from unrecognised command

Return from *Lib

Save file

Load file

Examine

Return for all information in machine readable format (argument = 0)

Return for all information in character string format (argument = 1)

Return for file title only, in machine readable format (argument = 2)

Return for file title and access, in character string format (argument = 3)

Catalogue Header

Load as

Open object

Close object

Get byte

Put byte

Get bytes

Put bytes

Read random access information

Set random access information

Read disc information

Read current users' information

Read file server date and time

Read 'End-of-file' status

Read object information

Reply to arguments 1 - 5

Reply to argument 6

Reply to argument 7

Set object attributes

Delete object

Read user environment

Set user boot option

Log off

Read single user's information

Read file server version number

Read disc free space

Create directory, specifying size

Set file server date and time

Create file

Read user free space

Set user free space

Read client UserId

Read current users' information (extended)

Read single user's information (extended)

Manager Interface

Read number of entries in password file (argument = 0)

Read entry from password file (argument = 1)

Write user profile in password file (argument = 2)

Add new user (argument = 3)

Remove user (argument = 4)

Set privilege (argument = 5)

Logoff user (argument = 6)

Shutdown server (argument = 7)

Error messages

www.riscos.com Technical Support:
Programmer's Reference Manual