32-bit File Server Calls
                         ------------------------
           Based on examining awServer 1.00, awServer 1.01, SoftMDFS,
    NetFS 5.90, NetFS 6.00, NetFS 6.07, NetFS 6.08, Advanced L4FS 2.09, 2.11

Summary
=======
      3 Examine ARG=4 examine 32-bit information
     18 ReadInfo ARG=8 read 32-bit information
     18 ReadInfo ARG=&BC test for 32-bit support
     38 Save file 32-bit
     39 Create file 32-bit
     40 Load file 32-bit
     41 Get 32-bit random access information
     42 Set 32-bit random access information
     43 Get Bytes 32-bit
     44 Put Bytes 32-bit
     45 Examine 32-bit
     46 Open Object 32-bit


Examine                                                    Function code=3
==========================================================================
This adds a 32-bit extended subfunction to Examine.

On entry
--------
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |              ARG              |
           | 4: All information, machine   |
           |    readable format, with      |
           |    32-bit file sizes          |
         8 +-------------------------------+
           |   Entry pointer to directory  |
         9 +-------------------------------+
           |  Number of entries to examine |
        10 +-------------------------------+
           |       Directory pathname,     |
           |        terminated by CR       |
         n +-------------------------------+

On exit
-------
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |  Number of entries returned   |
         5 +-------------------------------+
           |         Cycle number          |
         6 +===============================+
           |      32-bit load address      |
        10 +-------------------------------+
           |   32-bit execution address    |
        14 +-------------------------------+
           |     32-bit object length      |
        18 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
        19 +-------------------------------+
           | Returns &00. Padding to align?|
           |        Ownership byte?        |
        20 +-------------------------------+
           |      Date object created      |
        22 +-------------------------------+
           |           Probably            |
           |  System Internal Name (SIN)   |
        26 +-------------------------------+
           |       Returns &00000000       |
           |    Probably 4-byte padding    |
        30 +-------------------------------+
           | File name padded with spaces  |
        40 +===============================+
           |Next object as above bytes 6-39|
           +===============================+
           |        &80 terminator         |
           +-------------------------------+

Testing
-------
AL4FS v2.09 gives a Bad ARG error.


Read Info                                                 Function code=18
==========================================================================
This adds 32-bit extended subfunctions to ReadInfo.

On entry
-------- *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |              ARG              |
           | 7:   Read Unique ID           |
           | 8:   Read 32-bit information  |
           | &BC: Test for 32-bit support  |
         8 +-------------------------------+
           |       Object pathname,        |
           |       terminated by CR        |
         n +-------------------------------+

On exit
-------
If ARG=7 *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           | 0 = object not found          |
           | 1 = object is a file          |
           | 2 = object is a directory     |
         5 +-------------------------------+
           |  System Internal Name (SIN)   |
         9 +-------------------------------+
           |  Server filing system number  |
        10 +-------------------------------+
           |    Disc number? AL4FS=&00     |
        11 +-------------------------------+

When NetFS wants to create a unique object ID it makes a ReadInfo call with
ARG=7. If a Bad ARG error is returned it constructs a *INFO command. If the
returned data is &44 bytes long (a string &42 characters long plus <CR> plus
a &80 terminator), it looks like it came from an Acorn server and it
extracts the SIN from the returned string from &3C bytes in.

On exit
-------
If ARG=8 *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           | 0 = object not found          |
           | 1 = object is a file          |
           | 2 = object is a directory     |
         5 +-------------------------------+
           |   32-bit file load address    |
         9 +-------------------------------+
           |  32-bit file execute address  |
        13 +-------------------------------+
           |       32-bit file size        |
        17 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
        18 +-------------------------------+
           |      File creation date       |
        20 +-------------------------------+
           |    &00:Owner, <>&00:Public    |
        21 +-------------------------------+

On exit
-------
If ARG=&BC *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         3 +-------------------------------+
           |         Return Code           |
           | &00 = Server supports         |
           |                  32-bit calls |
           | <>0 = Server may not support  |
           |                  32-bit calls |
         4 +-------------------------------+
           |  String if return code <> 0   |
         n +-------------------------------+

When using a NetFS that supports 32-bit calls, after logging on a ReadInfo
call with ARG=&BC is made testing either the object "$$" or a zero byte. The
object name should be ignored. A server that does not support 32-bit calls
will return an error (usually Bad ARG or Bad name). A server that does
support 32-bit calls will return a receive block with return code &00.

NetFS modifies its behavior in the following ways:
* OSFILE 5:  32-bit uses ReadObjectInfo 8
             24-bit uses ReadObjectInfo 5
* OPEN:      32-bit uses OpenExtended which also returns object metadata
             24-bit uses Open, then ReadObjectInfo to get metadata
* CLOSE:     32-bit writes new load/exec addresses to set datestamp
             24-bit just closes

Testing
-------
AL4FS v2.09: ARG=&BC gives Bad ARG error. Any call examining "$$" times out
and the client gives a No reply error.


Save Object 32-bit                                        Function Code=38
==========================================================================
This function is the 32-bit extended version of Save Object.

On entry
-------- *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |     Data acknowledge port     |
         8 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
         9 +-------------------------------+
           |   32-bit file load address    |
        13 +-------------------------------+
           |  32-bit file execute address  |
        17 +-------------------------------+
           |       32-bit file size        |
        21 +-------------------------------+
           |  File name terminated by CR   |
         n +-------------------------------+

File server reply: *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |           Data port           |
         5 +-------------------------------+
           |    Maximum data block size    |
         7 +-------------------------------+

Loop:
  Transmit to data port
  Wait for reply on DataAck port
  Decrement count
  Loop if non-zero

File server final reply:
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
         5 +-------------------------------+
           |      File creation date       |
         7 +-------------------------------+
           |  Leaf name terminated by CR   |
         n +-------------------------------+


Create Object 32-bit                                      Function Code=39
==========================================================================
This function is the 32-bit extended version of Create Object.

On entry
-------- *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |     Data acknowledge port     |
           |  Ignored as no data transfer  |
         8 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
         9 +-------------------------------+
           |   32-bit file load address    |
        13 +-------------------------------+
           |  32-bit file execute address  |
        17 +-------------------------------+
           |       32-bit file size        |
        21 +-------------------------------+
           |  File name terminated by CR   |
         n +-------------------------------+

On exit: *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
         5 +-------------------------------+
           |      File creation date       |
         7 +-------------------------------+
           |  Leaf name terminated by CR   | **CHECK**
         n +-------------------------------+


Load Object 32-bit                                        Function Code=40
==========================================================================
This function is the 32-bit extended version of Load Object.

On entry
-------- *CHECKED AL4FS* *CHECKED NetFS 6.07*
         0 +-------------------------------+
           |    Standard Transmit block    |
         7 +-------------------------------+
           |           Data port           |
         8 +-------------------------------+
           |  File name terminated by CR   |
         n +-------------------------------+

File server (reply port): *CHECKED AL4FS* *CHECKED NetFS 6.07*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |   32-bit file load address    |
         8 +-------------------------------+
           |  32-bit file execute address  |
        12 +-------------------------------+
           |       32-bit file size        |
        16 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
        17 +-------------------------------+
           |      File creation date       |
        19 +-------------------------------+
           |  Leaf name terminated by CR   |
         n +-------------------------------+

A ReadData transaction takes place here.


Read 32-bit random access information                     Function Code=41  
==========================================================================
This function is the 32-bit version of Read Random Access Information.

On entry
-------- *CHECKED NetFS600, 607* *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |   File handle in FS format    |
         8 +-------------------------------+
           |             ARG               |
           | 0: read pointer, extent, size |
           |    (PTR#, EXT#, size          |
           |    (OSARGS 0, 2, 4)           |
         9 +-------------------------------+

On exit
------- *CHECKED NetFS600, 607* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           | 32-bit PTR: sequential pointer|
         8 +-------------------------------+
           | 32-bit EXT: file extent       |
        12 +-------------------------------+
           | 32-bit SIZE: space allocation |
        16 +-------------------------------+
           |      32-bit load address      |
        20 +-------------------------------+
           |      32-bit exec address      |
        24 +-------------------------------+

Testing
-------
AL4FS 2.09 gives Channel error for all calls.

NetFS 6.07/6.08 supplied with the Advanced Level 4 File Server sends the
ARG and handle the wrong way around. A server can detect this in the
following way:
    hnd%=RxBuf%?7:arg%=RxBuf%?8:IF hnd%=0 OR arg%>3 THEN SWAP hnd%,arg%


Set 32-bit random access information                      Function Code=42
==========================================================================
This function is the 32-bit version of Set Random Access Information.

On entry
-------- *CHECKED NetFS600, 607* *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |   File handle in FS format    |
         8 +-------------------------------+
           |             ARG               |
           | 0: sequential file pointer    |
           |    (PTR#, OSARGS 1)           |
           | 1: file extent                |
           |    (EXT#, OSARGS 3)           |
           | 2: set load/exec addresses    |
         9 +-------------------------------+
If ARG=0, ARG=1:
         9 +-------------------------------+
           |   32-bit information to set   |
        13 +-------------------------------+
If ARG=2:
         9 +-------------------------------+
           |      32-bit load address      |
        13 +-------------------------------+
           |      32-bit exec address      |
        17 +-------------------------------+

On exit
------- *CHECKED NetFS600, 607* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+

Testing
-------
AL4FS 2.09 gives a Channel error for all calls.

NetFS 6.07/6.08 supplied with the Advanced Level 4 File Server sends the
ARG and handle the wrong way around. A server can detect this in the
following way:
    hnd%=RxBuf%?7:arg%=RxBuf%?8:IF hnd%=0 OR arg%>3 THEN SWAP hnd%,arg%


GetBytes32                                                Function Code=43
==========================================================================
This function is the 32-bit extended version of GetBytes.

On entry
--------
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |             ????              |
         8 +-------------------------------+
           |             ARG               |
           | 0 : use supplied offset       |
           |<>0: use FS sequential pointer |
         9 +-------------------------------+
           |          Reply port           |
        10 +-------------------------------+
           |   File handle in FS format    |
        11 +-------------------------------+
           |    32-bit number of bytes     |
        15 +-------------------------------+
           |      32-bit file offset       |
           |         (if supplied)         |
        19 +-------------------------------+

A ReadData transaction takes place here.

On exit after data transfer
---------------------------
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           | &00=all ok                    |
           | &80=includes last byte of file|
         5 +-------------------------------+
           |  32-bit number of bytes read  |
         9 +-------------------------------+

Testing
-------
AL4FS: Uncertain what actions are happening. The call returns but the
returned data has no meaning, and the server doesn't enter into a data
transaction session.


PutBytes32                                                Function Code=44
==========================================================================
This function is the 32-bit extended version of PutBytes.

On entry
-------- *CHECKED NetFS 607*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |             ????              |
         8 +-------------------------------+
           |             ARG               |
           | 0 : use supplied offset       |
           |<>0: use FS sequential pointer |
         9 +-------------------------------+
           |        Ack. Reply port        |
        10 +-------------------------------+
           |   File handle in FS format    |
        11 +-------------------------------+
           |    32-bit number of bytes     |
        15 +-------------------------------+
           |      32-bit file offset       |
           |         (if supplied)         |
        19 +-------------------------------+

Reply
----- *CHECKED NetFS 607*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |           Data port           |
         5 +-------------------------------+
           |          Block size           |
         7 +-------------------------------+

Loop:
  Transmit to data port
  Wait for reply on DataAck port
  Decrement count
  Loop if non-zero
   
Final reply
----------- *CHECKED NetFS 607*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           | &00=all ok                    |
           | &80=includes last byte of file|
         5 +-------------------------------+
           |  32-bit number of bytes read  |
         9 +-------------------------------+
Testing
-------
AL4FS: Uncertain what actions are happening. The call returns but the
returned data has no meaning, and the server doesn't enter into a data
transaction session.


Examine32                                                 Function code=45
==========================================================================
This function is the 32-bit extended version of Examine.

On entry
-------- *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           |   Entry pointer to directory  |
           |   NetFS uses a 16-bit value   |
         9 +-------------------------------+
           |  Number of entries to examine |
        10 +-------------------------------+
           |      Directory pathname,      |
           |       terminated by CR        |
         n +-------------------------------+

On exit
------- *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |  Number of entries returned   |
         5 +-------------------------------+
           |     &00:Owner, &FF:Public     |
         6 +-------------------------------+
           |  Usually &FFFF but sometimes  |
           |        something else         |
           | This may be padding to align  |
           |      to 4-byte addresses      |
         8 +===============================+
           |      32-bit load address      |
        12 +-------------------------------+
           |   32-bit execution address    |
        16 +-------------------------------+
           |     32-bit object length      |
        20 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
        21 +-------------------------------+
           |         &00 : unknown         |
        22 +-------------------------------+
           |      Date object created      |
        24 +-------------------------------+
           |  System Internal Name (SIN)   |
        28 +-------------------------------+
           |   4 bytes of left-over data   |
        32 +-------------------------------+
           | File name padded with spaces  |
        nn +-------------------------------+
           |             <cr>              |
      nn+1 +-------------------------------+
           | &00 bytes padding to rxbuf+43 |
           |       to 4-byte address       |
        44 +===============================+
           |Next object as above bytes 8-43|
           +===============================+
           |        &80 terminator         |
           +-------------------------------+


OpenObject32                                              Function code=46
==========================================================================
This function is the 32-bit extended version of Open Object.

On entry
-------- *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |   Transmit block (shown on    |
           |         summary page)         |
         7 +-------------------------------+
           | 0  : create a new file, delete|
           |      data in any existing file|
           | <>0: object must already exist|
         8 +-------------------------------+
           | 0  : open object for update   |
           | <>0: open object for read only|
         9 +-------------------------------+
           | Object name, terminated by CR |
         n +-------------------------------+

On exit
------- *CHECKED NetFS* *CHECKED AL4FS*
         0 +-------------------------------+
           |    Receive block (shown on    |
           |         summary page)         |
         4 +-------------------------------+
           |    File handle in FS format   |
         5 +-------------------------------+
           | 0 = object not found          |
           | 1 = object is a file          |
           | 2 = object is a directory     |
         6 +-------------------------------+
           |         Access byte,          |
           |   bits 7-0: M P D L W R w r   |
         7 +-------------------------------+
           |     &00:Owner, &FF:Public     |
         8 +-------------------------------+
           |       32-bit object size      |
        12 +-------------------------------+
           |     32-bit disk allocation    |
        16 +-------------------------------+
           |(possibly: 32-bit load address)|
        20 +-------------------------------+
           |(possibly: 32-bit exec address)|
        24 +-------------------------------+


==========================================================================
Notes: Ownership is &00 vs <>&00, but lots of code explicitly tests for
&00 vs &FF, so servers should return &00 and &FF.

SIN (System Internal Name) is a 4-byte number which is typically the start
sector number of the object or the object's map on the server disk. Servers
serving disks smaller than 4G this will often be the 3-byte SIN in the low
bytes and the disk number in the top byte.

History
=======
24-Jul-2024: Examined NetFS 5.90 and 6.00 source.
26-Jul-2024: Testing response with Advanced Level 4 File Server 2.09.
Disassembling date-expired AL4FS 2.11 to examine functionality.
Disassembling NetFS 6.07 supplied with AL4FS 2.09.
31-Jul-2024: Disassembling NetFS 6.08 supplied with AL4FS 2.11.

References
==========
Castle source for NetFS 5.90, NetFS 6.00 - doesn't define fsOp numbers.
aund32 fs_proto.h file, Harris,Tatham,Woodcock,Inglis - defines fsOp numbers.
Advanced Level 4 File Server v2.09 - experimentation.
awServer 1.00 and 1.01 - 32bit implementation wrong.
Disassembly of NetFS 6.07, 6.08 supplied with Advanced Level 4 File Server 2.09.