BLib.NetFS - Network Filing System Library Routines
          ===================================================
                     File: NetFS - Update: 1.03
              Author: J.G.Harston - Date: 07-Jan-1992


  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 the supplied file server function code.

  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

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

Cat Header      NetFS_Op( 4, pathname$)
---------------------------------------
On exit:
    X%+4  directory leafname padded to ten spaces
    X%?14 character indicating ownership of directory
    X%+15 three space characters
    X%+18 disk name padded to 16 spaces
    X%?31 <cr>
    X%?32 &80

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

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 PTR       X%?8=0:X%!9=size%:A%=FNNetFS_OpN(13, handle, 12, "")
--------------------------------------------------------------------
On exit:
    no data returned

Write EXT       X%?8=1:X%!9=size%:A%=FNNetFS_OpN(13, handle, 12, "")
--------------------------------------------------------------------
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

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 object 24-bit extent
    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=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 object 24-bit 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
    X%!7  24-bit disk size

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

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

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)
-----------------------------------

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)
-----------------------------------