BLib.NetFS - Network Filing System Library Routines
          ===================================================
                     File: NetFS - Update: 1.03
              Author: J.G.Harston - Date: 07-Jan-1992
             Updated with 32-bit FSOp call information

  The NetFS library provides functions to communicate with a network file
server with the Network Filing System file server protocol interface. The
physical network link or links used by the transmitted messages is
irrelevant, as long as the link is accessed through the standard Acorn
Networking system calls.

Requirements and Dependancies
=============================
  The library requires a global control block large enough to hold the data
required for the calls accessible with X% holding the address of this block,
and Y% holding X% DIV 256. A control block size of 128 bytes is sufficient
for most calls, and is the largest than can be used with the Tube. This can
easily be set up with DIM ctrl% 127 near the start of the program and
X%=ctrl%:Y%=X%DIV256 at the begining of the major program code and at the
start of any main program loop.

Definitions
===========
station%  - two-byte station number, formed by station+256*network
function% - function code
arg%      - supplementary call argument
name$     - string parameter, filename, directory name, command name, etc.
offset%   - offset within control block to start of string parameter
context%  - network user context, csd, lib and urd
data%     - generic four-byte data
dummy%    - dummy value to hold unused return data
handle%   - file handle in file server format
cdate%,mdate% - two-byte creation/modification date in filing system format:
        byte 0 : b0-b4 : day of month 0-31
               : b5-b7 : (year-1981) DIV 16
        byte 1 : b0-b3 : month 0-15
               : b4-b7 : (year-1981) MOD 16
ctime%,mtime% - three-byte creation/modification time in filing system format:
        byte 0 : hour 0-23
        byte 1 : minute 0-59
        byte 2 : second 0-59

File Server Operations
======================
DEFFNNetFS_Op(function%, name$)
DEFFNNetFS_OpN(function%, arg%, offset%, name$)

  File server operations take a varying amount of data. Most operations take
between none and three bytes of data plus an optional string parameter. Each
function returns the file server return code. This will be zero if the call
successfully completed. If NetFS is not present, then the return code will
be either the supplied file server function code or a file server error
number.

  NetFS_Op() sends a file server command block to the current file server.
function% is the file server function and name$ is any string parameter to
pass. Most file server operations can be done with NetFS_Op() with arguments
passed as characters prepended to the string parameter, as in the following
example to read an object's creation date:

    IF FNNetFS_Op(18,CHR$1+filename$)=0 THEN cdate%=X%!5

  NetFS_OpN() sends a variable-sized command block to the current file
server. function% is the file server function, arg% is the first argument
for the file server call and offset% is the length of data already in the
control block - the offset to where name$ should be stored in the control
block. If no string is required, pass name$ as "" and offset% as the offset
to the end of the control block.

  Any other parameters must be put in the control block before calling. The
following example writes the creation date of a file:

    X%!8=cdate%:A%=FNNetFS_OpN(19,5,10,filename$)

File Server Calls
=================
Command line     NetFS_Op( 0, command$)
---------------------------------------
On exit:
    X%?2 = 0  - Command complete

    X%?2  =1  - *Save
    X%!4  File load address
    X%!8  File exec address
    X%!12 File 24-bit size
    X%+15 Filename, terminated by <cr>

    X%?2  =2  - *Load
    X%!4  File load address
    X%?8  =&FF - use load address, <>&FF - use file's load address
    X%+9  Filename, terminated by <cr>

    X%?2  =3  - *Cat
    X%+4  Directory name, terminated by <cr>

    X%?2  =4  - Display information, eg *Info
    X%+4  String of information, terminated by &80

    X%?2  =5  - *I AM
    X%?4  URD handle in file server format
    X%?5  CSD handle in file server format
    X%?6  LIB handle in file server format
    X%?7  Boot option in bits 0-3

    X%?2  =6  - *SDisc
    X%?4  URD handle in file server format
    X%?5  CSD handle in file server format
    X%?6  LIB handle in file server format

    X%?2  =7  - *Dir
    X%?4  CSD handle in file server format

    X%?2  =8  - Unrecognised command
    X%+4  Command string, terminated by <cr>

    X%?2  =9  - *Lib
    X%?4  LIB handle in file server format

    X%?2  =10 - Disk information
    X%?2  =11 - User information

Save file        NetFS_Op( 1, ...)
----------------------------------

Load file        NetFS_Op( 2, ...)
----------------------------------

Examine          NetFS_Op( 3, CHR$arg+CHR$ptr+CHR$num+filename$)
----------------------------------------------------------------
On exit, if arg=0, read info in machine format:
    X%?4  number of objects examined
    X%?5  cycle number
    X%+6  object title padded with spaces
    X%!16 load address
    X%!20 exec address
    X%?24 object access bits 7-0: MPDLwrWR
    X%!25 creation date
    X%!27 object system internal name (Acorn)
    X%?27 main account number (SJ)
    X%?28 b0-b3=main account number b8-b11, b4-b7=aux acc b8-b11 (SJ)
    X%?29 auxilary account number (SJ)
    X%!30 object 24-bit size
    X%?33 cycle number of next object

On exit, if arg=1, read info as character string:
    X%?4  number of object examined
    X%?5  cycle number
    X%+6  character string of all information, terminated by &80

On exit, if arg=2, read file title:
    X%?4  number of objects examined
    X%?5  cycle number
    X%?6  =10, object name length
    X%+7  object name padded with spaces to 10 characters

On exit, if arg=3, read file title and access as character string:
    X%?4  number of objects examined
    X%?5  cycle number
    X%+6  object name padded with spaces, followed by access string

On exit, if arg=4, read 32-bit info in machine format:
    X%?4  number of objects examined
    X%?5  cycle number
    X%!6  load address
    X%!10 exec address
    X%!14 length
    X%?18 object access bits 7-0: MPDLwrWR
    X%+19 onwards:  uncertain
    X%!20 possibly: creation date
    X%!22 possibly: system internal name (SIN)
    X%+30 object title padded with spaces

Cat Header       NetFS_Op( 4, pathname$)
----------------------------------------
On exit:
    X%+4  Catalog header as a string to display terminated with <cr>,&80
          formatted to fit on a single 32-character line. This will be
          displayed as the first line of a catalog on a System or Atom, and
          is laid out conventionally as:
             DirctyName PUB  TheDiskNameHere
          or DirctyName OWN  TheDiskNameHere
    X%+4  directory leafname padded to ten spaces
    X%?14 space character
    X%?15 character indicating ownership of directory 'O' or 'P'
    X%+16 four space characters, or 'WN'/'UB' followed by two spaces
    X%+20 disk name padded to a maximum of 16 spaces
    X%?n  <cr>
    X%?m  &80

Load as command  NetFS_Op( 5, ...)
----------------------------------

Open             NetFS_Op( 6, CHR$create+CHR$read+filename$)
------------------------------------------------------------
On entry:
    create = 0 - create a new file
           <>0 - object must already exist
    read   = 0 - open object for update
           <>0 - open object for read only
On exit:
    X%?4  file handle in file server format

Close            NetFS_Op( 7, CHR$handle)
-----------------------------------------
On exit:
    no data returned

Get Byte         NetFS_Op( 8, ...)
----------------------------------

Put Byte         NetFS_Op( 9, ...)
----------------------------------

Get Bytes        NetFS_Op(10, ...)
----------------------------------

Put Bytes        NetFS_Op(11, ...)
----------------------------------

Read Info        NetFS_Op(12, CHR$handle+CHR$type)
--------------------------------------------------
On entry:
    handle = file handle in file server format
    type   = 0 - read file PTR
           = 1 - read file EXT
           = 2 - read file allocated space
On exit:
    X%!4  returned 24-bit file info

Write Info       X%?8=type:X%!9=data%:A%=FNNetFS_OpN(13, handle, 12, "")
------------------------------------------------------------------------
On entry:
    type   = 0 - read file PTR
           = 1 - read file EXT
           = 2 - read file allocated space
    data%  = 24-bit value to write
    handle = file handle in file server format
On exit:
    no data returned

Read Disks       NetFS_Op(14, CHR$first+CHR$number)
---------------------------------------------------
On entry:
    first  = first drive number
    number = number of drives to examine
On exit:
    X%?4  number of drives examined
    X%?5  drive number of first drive
    X%+6  drive name padded to 16 characters
    X%?22 drive number of second drive
    etc.

Read Users       NetFS_Op(15, CHR$first+CHR$number)
---------------------------------------------------
On entry:
    first  = first user to examine
    number = number of users to return
On exit:
    X%?4  number of entries returned
    X%?5  station number user logged on at
    X%?6  network number user logged on at
    X%+7  user name, terminated by <cr>
    X%?n  =0 - privileged, <>0 - not privileged
    etc.

Read Date&Time   NetFS_Op(16, "")
---------------------------------
On exit:
    X%!4  current date
    X%!6  current time

Read EOF         NetFS_Op(17, CHR$handle)
-----------------------------------------
On exit:
    X%?4  =0 - not EOF, <>0 - at or past EOF

Read Info        NetFS_Op(18, CHR$arg+filename$)
------------------------------------------------
On exit, arg=1, read object creation date:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  creation date

On exit, arg=2, read load and execute address:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  load address
    X%!9  exec address

On exit, arg=3, read object extent:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  object 24-bit extent

On exit, arg=4, read access and ownership:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%?5  object access bits 7-0: MPDLwrWR
    X%?6  object ownership, &00=owner, &FF=public

On exit, arg=5, read all object attributes:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  load address
    X%!9  exec address
    X%!13 24-bit object size
    X%?16 object access bits 7-0: MPDLwrWR
    X%!17 creation date
    X%?19 object ownership, &00=owner, &FF=public

On exit, arg=6, read access and cycle number of dir:
    X%?4  undefined
    X%?5  0
    X%?6  =10, object name length
    X%+7  directory name, padded to ten characters
    X%?17 directory ownership, &00=owner, &FF=public
    X%?18 cycle number

On exit, arg=7, read system internal name:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%?5  disk number
    X%!6  system internal name
    X%?9  file server disk number
    X%?10 file server filing system number

On exit, arg=8, read 32-bit object attributes:
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  load address
    X%!9  exec address
    X%!13 32-bit object size
    X%?17 object access bits 7-0: MPDLwrWR
    X%!18 creation date
    X%?20 object ownership, &00=owner, &FF=public

On exit, arg=64, read creation and update dates (SJ):
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  object creation date
    X%!7  object creation time
    X%!10 object modification date
    X%!12 object modification time

On exit, arg=65, read account numbers (SJ):
    X%?4  object type, 0=not found, 1=file, 2=directory
    X%!5  object main account number
    X%!7  object auxilary account number

Write Info       X%!8=load%:X%!12=exec%:X%?16=attr:
                 A%=FNNetFS_OpN(19, 1, 17, filename$)
-----------------------------------------------------
On exit:
    no returned data

Write Load       X%!8=load%:A%=FNNetFS_OpN(19, 2, 12, filename$)
----------------------------------------------------------------
On exit:
    no returned data

Write Exec       X%!8=exec%:A%=FNNetFS_OpN(19, 3, 12, filename$)
----------------------------------------------------------------
On exit:
    no returned data

Write Attr      NetFS_Op(19, CHR$4+CHR$attr+filename$)
------------------------------------------------------
On exit:
    no returned data

Write Date       X%!8=mdate:A%=FNNetFS_OpN(19, 5, 10, filename$)
----------------------------------------------------------------
On exit:
    no returned data

Write Date+Time  X%!8=cdate:X%!10=ctime:X%!13=mdate:X%!15=mtime:
                 A%=FNNetFS_OpN(19,64,18,filename$)
---------------------------------------------------------------
On exit:
    no returned data

Delete           NetFS_Op(20, filename$)
----------------------------------------
On exit:
    X%!4  load address
    X%!8  exec address
    X%!12 24-bit onject size

Read Environment NetFS_Op(21, "")
---------------------------------
On exit:
    X%?4  =16, length of disk name
    X%+5  disk name padded to 16 characters
    X%+21 CSD name padded to 10 characters
    X%+31 LIB name padded to 10 characters

Set Boot         NetFS_Op(22, CHR$option)
-----------------------------------------
On exit:
    no returned data

Logoff           NetFS_Op(23, "")
---------------------------------
On exit:
    no returned data

User Info        NetFS_Op(24, username$)
----------------------------------------
On exit:
    X%?4  =0 - unprivileged, <>0 - privileged
    X%?5  station number user logged on at
    X%?6  network number user logged on at

FS Version       NetFS_Op(25, "")
---------------------------------
On exit:
    X%+4  File Server version string in format
          "SJ Research File Server ver 2.00/MDFS",
    start of string: "SJ", "Acorn", etc
    end of string:   "MDFS", "HDFS", "FDFS", etc.

Read Free        NetFS_Op(26, diskname$)
----------------------------------------
On exit:
    X%!4  24-bit free space on disk in 256-byte blocks
    X%!7  24-bit disk size in 256-byte blocks

Create Dir       NetFS_Op(27, CHR$blocks+pathname$)
---------------------------------------------------
On exit:
    no returned data

Set Time         X%!7=date:X%!9=time:A%=FNNetFS_OpN(28, date, 12, "")
---------------------------------------------------------------------
On exit:
    no returned data

User Free        NetFS_Op(30, username$)
----------------------------------------
On entry:
    username$ = username or "" for client
On exit:
    X%!4  24-bit space available for user in 256-byte blocks

Set Free         X%!7=space%:A%=FNNetFS_OpN(31, space%, 11, username$)
----------------------------------------------------------------------
On exit:
    no returned data

WhoAmI           NetFS_Op(32, "")
---------------------------------
On exit:
    X%+4  client username, terminated with <cr>

Read Users Extn  NetFS_Op(33, CHR$first+CHR$number)
---------------------------------------------------
On exit:
    X%?4  number of entries returned
    X%?5  station number user logged on at
    X%?6  network number user logged on at
    X%?7  task number of user
    X%+8  user name, terminated with <cr>
    X%+n  station number of next user

User Info Extn   NetFS_Op(34, username$)
----------------------------------------
On exit:
    X%?4  number of entries returned
    X%?5  station number user logged on at
    X%?6  network number user logged on at
    X%?7  task number of user

FSOp 35          NetFS_Op(35, ...)
----------------------------------

Manager 0        NetFS_Op(36, CHR$0)
------------------------------------

Manager 1        NetFS_Op(36, CHR$1+CHR$usernumber)
---------------------------------------------------

Manager 2        X%!8=... :A%=FNNetFS_OpN(36, 2, length, "")
------------------------------------------------------------

Manager 3        NetFS_Op(36, CHR$3+username$)
----------------------------------------------

Manager 4        NetFS_Op(36, CHR$4+username$)
----------------------------------------------

Manager 5        NetFS_Op(36, CHR$5+username$+CHR$13+CHR$priv)
--------------------------------------------------------------

Manager 6        NetFS_Op(36, CHR$6+username$)
----------------------------------------------

Manager 7        NetFS_Op(36, CHR$7)
------------------------------------

Save 32-bit      NetFS_Op(38, ...)
----------------------------------

Create 32-bit    NetFS_Op(39, ...)
----------------------------------

Load 32-bit      NetFS_Op(40, ...)
----------------------------------

Get 32-bit Info  NetFS_Op(41, CHR$0+CHR$handle)
-----------------------------------------------
On entry:
    handle = file handle in file server format
On exit:
    X%!4  returned 32-bit file PTR
    X%!8  returned 32-bit file EXT
    X%!12 returned 32-bit file allocated space

Set 32-bit Info  X%?8=type:X%!9=data%:A%=FNNetFS_OpN(42, type, 13, "")
----------------------------------------------------------------------
On entry:
    data%  = 32-bit value to write
    type   = 0 - set file PTR
           = 1 - set file EXT
           = 2 - set file allocated space
    handle = file handle in file server format
On exit:
    no data returned

GetBytes 32-bit  A%=FNNetFS_Op(43, ...)
---------------------------------------

PutBytes 32-bit  A%=FNNetFS_Op(44, ...)
---------------------------------------

Examine 32-bit   NetFS_Op(45, CHR$ptr+CHR$0+CHR$num+CHR$arg+filename$)
----------------------------------------------------------------------
On exit, if arg=1, read 32-bit info in machine format:
    Uncertain about these details:
    X%?4  number of objects examined
    X%?5  cycle number
    X%?7  object type, 0=not found, 1=file, 2=directory
    X%!8  load address
    X%!12 exec address
    X%!16 32-bit length
    X%?20 object access bits 7-0: MPDLwrWR
    X%+21 onwards:  uncertain
    X%!22 possibly: creation date
    X%!24 possibly: system internal name (SIN)
    X%+32 object title padded with spaces
    X%+42 etc.

Open 32-bit      NetFS_Op(46, CHR$create+CHR$read+filename$)
------------------------------------------------------------
On entry:
    create = 0 - create a new file
           <>0 - object must already exist
    read   = 0 - open object for update
           <>0 - open object for read only
On exit:
    X%?4  file handle in file server format
    X%?5  object type, 0=not found, 1=file, 2=directory
    X%?6  object access bits 7-0: MPDLwrWR
    X%?7  object ownership, &00=owner, &FF=public
    X%!8  returned 32-bit file EXT
    X%!12 returned 32-bit file allocated space

Read Accounts    X%!8=first:X%!10=number:X%!12=disc:
                 A%=FNNetFS_OpN(64, arg, 13, "")
----------------------------------------------------

SysInfo 0        NetFS_Op(65, CHR$0)
------------------------------------

SysInfo 1        NetFS_Op(65, CHR$1+CHR$printernumber)
------------------------------------------------------

SysInfo 5        NetFS_Op(65, CHR$5)
------------------------------------

SysInfo 6        NetFS_Op(65, CHR$6+CHR$printer)
------------------------------------------------

SysInfo 7        NetFS_Op(65, CHR$7)
------------------------------------

SysInfo 8        NetFS_Op(65, CHR$8+CHR$messagelevel)
-----------------------------------------------------

SysInfo 10       NetFS_Op(65, CHR$10+CHR$printersetting)
--------------------------------------------------------

SysInfo 11       NetFS_Op(65, CHR$11)
-------------------------------------

SysInfo 12       NetFS_Op(65, CHR$12+CHR$privilege)
---------------------------------------------------

SysInfo 15       NetFS_Op(65, CHR$15+CHR$number+CHR$first)
----------------------------------------------------------

SysInfo 16       X%!8=... :A%=FNNetFS_OpN(65, 16, length, "")
-------------------------------------------------------------

Encryption       NetFS_Op(66, "")
---------------------------------

Backup 0         NetFS_Op(67, CHR$0)
------------------------------------

Backup 1         X%!8=offset:X%!10=number:A%=FNNetFS_OpN(67, 1, 12, "")
-----------------------------------------------------------------------

Backup 2         NetFS_Op(67, CHR$2)
------------------------------------

Backup 3         X%!8=... :A%=FNNetFS_OpN(67, 3, length, "")
------------------------------------------------------------

Backup 4         NetFS_Op(67, CHR$4)
------------------------------------