Difference between revisions of "OSARGS"

From BeebWiki
Jump to: navigation, search
(→‎Special handles)
m (Slight tweeks.)
Line 4: Line 4:
 
==Specification==
 
==Specification==
 
{| cellpadding="0" cellspacing="0"
 
{| cellpadding="0" cellspacing="0"
−
|  6502  ||  Z80  ||  6809  ||  PDP11  ||  80x86  ||  32016  ||  ARM  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
+
|  6502  ||  Z80  ||  6809  ||  PDP11  ||  80x86  ||  32016  ||  ARM  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
 
|- align="center" valign="top"
 
|- align="center" valign="top"
 
| A || A  || A  || R0 || AL || R1 || R0 || align="left" | = function code || preserved if not supported, but see notes.
 
| A || A  || A  || R0 || AL || R1 || R0 || align="left" | = function code || preserved if not supported, but see notes.
Line 17: Line 17:
 
|}
 
|}
  
−
If the data word is not used, then it is ignored and so X/HL/R2/BX/R3 may be left set to anything on entry.
+
If the data word is not used, then it is ignored and so X/HL/R2/BX/R3 may be
 +
left set to anything on entry.
  
 
{| cellpadding="0" cellspacing="0"
 
{| cellpadding="0" cellspacing="0"
Line 77: Line 78:
 
:byte 0  = handle in internal format
 
:byte 0  = handle in internal format
 
:byte 1-2 = fileserver station number
 
:byte 1-2 = fileserver station number
−
:byte 3 = handle information:&nbsp;&nbsp;&nbsp;<li>b0: sequence number&nbsp;&nbsp;&nbsp;<li>b1: known to be a directory&nbsp;&nbsp;&nbsp;<li>b2: thought to be the URD&nbsp;&nbsp;&nbsp;&lt;li>b3: thought to be the CSD&nbsp;&nbsp;&nbsp;<li>b4: thought to be the LIB&nbsp;&nbsp;&nbsp;<li>b5: current context&nbsp;&nbsp;&nbsp;<li>b6: EOF flag, next BGET will generate an error&nbsp;&nbsp;&nbsp;<li>b7: writable
+
:byte 3 = handle information:&nbsp;&nbsp;&nbsp;<li>b0: sequence number&nbsp;&nbsp;&nbsp;<li>b1: known to be a directory&nbsp;&nbsp;&nbsp;<li>b2: thought to be the URD&nbsp;&nbsp;&nbsp;&amp;lt;li>b3: thought to be the CSD&nbsp;&nbsp;&nbsp;<li>b4: thought to be the LIB&nbsp;&nbsp;&nbsp;<li>b5: current context&nbsp;&nbsp;&nbsp;<li>b6: EOF flag, next BGET will generate an error&nbsp;&nbsp;&nbsp;<li>b7: writable
 
|- valign="top"
 
|- valign="top"
 
| &FD &nbsp;|| Write filing system context. HADFS implements:
 
| &FD &nbsp;|| Write filing system context. HADFS implements:
Line 160: Line 161:
  
 
==Special handles==
 
==Special handles==
−
When reading PTR and EXT from 8-bit BASIC, the data parameter is BASIC's integer store, which will be set to the channel as the last item evaluated. That means that PTR#0 and EXT#0 pass a data value of zero; OSARGS 0,0 and OSARGS 2,0 do not change the data word; this means that in 8-bit BASICs PTR#0 and EXT#0 return zero, being the unchanged data word set to the channel.
+
When reading PTR and EXT from 8-bit BASIC, the data parameter is BASIC's
 +
integer store, which will be set to the channel as the last item evaluated.
 +
That means that PTR#0 and EXT#0 pass a data value of zero; OSARGS 0,0 and
 +
OSARGS 2,0 do not change the data word; this means that in 8-bit BASICs
 +
PTR#0 and EXT#0 return zero, being the unchanged data word set to the
 +
channel.
  
−
This means that other BASIC have the ability to use PTR#0 and EXT#0 to return information specific to that implementation. Some BASICs or operating systems allow other special handles to return specific information. Some operating systems allow BPUT#0 and BGET#0 to access the VDU and keyboard, so allow PTR#0, EXT#0 and EOF#0 to access keyboard or VDU information.
+
This means that other BASIC have the ability to use PTR#0 and EXT#0 to
 +
return information specific to that implementation. Some BASICs or operating
 +
systems allow other special handles to return specific information. Some
 +
operating systems allow BPUT#0 and BGET#0 to access the VDU and keyboard, so
 +
allow PTR#0, EXT#0 and EOF#0 to access keyboard or VDU information.
  
 
See [[Handles#Special_cases|Special handles]].
 
See [[Handles#Special_cases|Special handles]].
Line 188: Line 198:
  
 
===DFS===
 
===DFS===
−
Acorn DFS 0.xx and 1.xx implements &FF to &02. DFS 2.xx and later also implements &03.
+
Acorn DFS 0.xx and 1.xx implements &FF to &02. DFS 2.xx and later also
 +
implements &03.
  
 
===HDFS===
 
===HDFS===
−
Andrew Duggan's Hierarchial DFS implements OSARGS &03,Y as 'Read allocated space' instead of 'Write extent'.
+
Andrew Duggan's Hierarchial DFS implements OSARGS &03,Y as 'Read allocated
 +
space' instead of 'Write extent'.
  
 
===Watford DFS===
 
===Watford DFS===
−
Implements &FE to &02. OSARGS &FE preserves A, so the returned data has to be examined to see if the call has been acted on with code such as:
+
Implements &FE to &02. OSARGS &FE preserves A, so the returned data has to
 +
be examined to see if the call has been acted on with code such as:
 
     drive%=FNargs(&FE,-1)AND&FF
 
     drive%=FNargs(&FE,-1)AND&FF
 
drive% will be &FF if not supported, or the drive number if it is.
 
drive% will be &FF if not supported, or the drive number if it is.
  
 
===NFS===
 
===NFS===
−
NFS 3.34 returns the command line address incorrectly. It points to the first non-'*' character of the command, not the first character of the parameters. NFS 3.60 and later return the command line address correctly. NFS 3.60 and later return A<>2 from OSARGS 2,0 to indicate this.
+
NFS 3.34 returns the command line address incorrectly. It points to the
 +
first non-'*' character of the command, not the first character of the
 +
parameters. NFS 3.60 and later return the command line address correctly.
 +
NFS 3.60 and later return A<>2 from OSARGS 2,0 to indicate this.
  
 
===ADFS===
 
===ADFS===
Line 207: Line 223:
  
 
===Sprow ARM7 CoPro===
 
===Sprow ARM7 CoPro===
−
When reading the current filing system with OS_Args all three parameters must be zero, including the data parameter. <code>'''SYS "OS_Args",0,0,data'''</code> does not return the filing system number unless ''data'' is zero. The ''data'' parameter cannot be left set to a random value as it can when calling on other platforms. ARM BBC BASIC translates calls to &FFDA correctly setting R2 to zero.
+
When reading the current filing system with OS_Args all three parameters
 +
must be zero, including the data parameter. <code>'''SYS "OS_Args",0,0,data'''</code>
 +
does not return the filing system number unless ''data'' is zero. The ''data''
 +
parameter cannot be left set to a random value as it can when calling on other
 +
platforms. ARM BBC BASIC translates calls to &FFDA correctly setting R2 to zero.
  
 
[[User:Jgharston|Jgharston]] 16:55, 6 November 2009 (UTC)
 
[[User:Jgharston|Jgharston]] 16:55, 6 November 2009 (UTC)

Revision as of 13:38, 17 October 2020

Read or write information on open objects or the filing system

Specification

 6502   Z80   6809   PDP11   80x86   32016   ARM  On entry: On exit:
A A A R0 AL R1 R0 = function code preserved if not supported, but see notes.
Y E Y R1 AH R2 R1 = file handle or 0 preserved
X =>four-byte data word in zero page   preserved, data word updated
HL X R2 BX =>four-byte data word preserved, data word updated
R3 R2 = four-byte data word any returned four-byte data word

If the data word is not used, then it is ignored and so X/HL/R2/BX/R3 may be left set to anything on entry.

Functions  handle<>0 handle=0
&80 Read file handle internal info
&FD Read context   Return version and capabilities
&FE Write context   Return last drive used
&FF Ensure open file to media Ensure all open files to media
&00 Read PTR Read filing system number
&01 Write PTR Read address of command tail
&02 Read EXT Read NFS version
&03 Write EXT Read libfs number
&04 Read size allocated to file Read disk space used
&05 Read EOF Read disk free space
&06 Ensure file size of open file
&07 Convert file handle to filename
&08 Inform change in image filestamp

Functions, handle<>0

&00 Reads the sequential pointer of the open object.
&01 Writes the sequential pointer of the pen file. If PTR is moved past the end of an output file, the file is extended with zeroes and zero returned in A, otherwise A = &FF on exit. Some filing systems do not write zeroes; the contents of the new part of the file are undefined. If PTR is moved past the end of an input file, an error is generated. The EOF-error-flag is cleared. The PTR of an open directory cannot be written.
&02 Reads the extent of the open object.
&03 Writes the extent of the open object. If the length of the file is reduced, the end disappears. If the length is increased, the file is extended as with function &01 and zero is returned in A, otherwise A = &FF on exit. The EOF-error-flag is cleared. The EXT of an open directory cannot be written.
&04 Reads the space allocated to the open object. This will be at least the current extent of the object, and determines how many more bytes can be written to the object before the object has to be extended or the write fails with a "Can't extend" error.
&05 Reads the EOF for the open object. If PTR=EXT then &FFFFFFFF is returned, otherwise 0 is returned.
&06 Ensures the open file is allocated the specified amount of space. Returns the actual amount of space allocated.
&07 Convert file handle to filename (RISC OS).

The data word in R2 points to a buffer, the size of which is given in R5. On exit, the data word in R2 is preserved, the buffer contains the filename as a NUL-terminated string, and R5 is decreased by the number of characters in the filename excluding the NUL. The NUL is addressed by R2 + R5entry - R5exit.

&08 Inform the underlying file system of new image stamp in data word.
&80 Read information on handle. Returns four bytes of data:
byte 0 = handle in internal format
byte 1-2 = fileserver station number
byte 3 = handle information:   
  • b0: sequence number   
  • b1: known to be a directory   
  • b2: thought to be the URD   &lt;li>b3: thought to be the CSD   
  • b4: thought to be the LIB   
  • b5: current context   
  • b6: EOF flag, next BGET will generate an error   
  • b7: writable
    • &FD   Write filing system context. HADFS implements:
  • 25: Currently Selected Directory
  • 26: Currently Selected Library
  • 27: User Root Directory
    • &FE   Read filing system context. HADFS implements:
  • 25: Currently Selected Directory
  • 26: Currently Selected Library
  • 27: User Root Directory

    • RISC OS: Returns the filing system information word in the data word and the stream information for the handle in A or R0. On 8-bit systems only the bottom 8 bits of the stream information word will be returned.

  • b0
  • b1
  • b2
  • b3: Interactive stream
  • b4: Unbuffered stream that directly supports OSGBPB
  • b5: Object is a directory
  • b6: Object is readable
  • b7: Object is writable
  • b8: Object has been written to
  • b9: EOF flag, next BGET will generate an error
  • b10: Stream is unbuffered
  • b11: Stream is unopened, no other bits have any significance
  • b12: Stream is critical
  • b13: Data lost on this stream
  • b14: Image file busy
  • b15
    • &FF Ensures any buffered data for the open file is written to the media.

    Functions, handle=0

    &00 Return filing system number in A: 
    0 No current filing system         20 RawKbd:
1 1200 baud cassette filing system 21 DeskFS:
2 300 baud cassette filing system  22 Computer Concepts RomFS:
3 ROM filing system                23 RamFS:
4 Disk filing system               24 RISCiXFS:
5 Econet network filing system     25 Streamer:
6 Teletext/Prestel telesoftware    26 SCSIFS:
7 IEEE filing system               27 Digitiser:
8 Acorn ADFS                       28 Scanner:
9 Host filing system               29 MultiFS:
10 Videodisk filing system
11                                 33 NFS:
12 RAM filing system  NetPrint:    37 CDFS:
13                    Null:        43 DOSFS:
14                    Printer:     46 ResourceFS:
15                    Serial:      47 PipeFS:
16 Harston ADFS
17                    Vdu:         53 DeviceFS:
18                    RawVdu:      54 Parallel:
19                    Kbd:
    &01 Returns the address of the command line tail, any parameters after a filename. The character at the address is the first non-space character after the name of the command (for example the 2 in *FORM80 2.) The address will always be in the I/O processor.
    &02 Returns A=0 for ANFS 4.00+, A=1 if later bug-fixed versions of NFS, returns A=2 if early bug-ridden NFS or if call unsupported.
    &03 Returns libfs filing system number in A.
    &04 Returns used space on the device with the currently selected directory on.
    &05 Returns free space on the device with the currently selected directory on.
    &FD Returns version number*10 in BCD in A and filing system capability flags in the data word.
    &FE Returns the last drive accessed in the data word.
    &FF  Ensures any buffered data for all open files is written to the media.

    Calling from BBC BASIC

    • ptr=PTR#ch calls OSARGS 0,ch
    • PTR#chn=ptr calls OSARGS 1,ch
    • ptr=EXT#ch calls OSARGS 2,ch
    • EXT#ch=ptr calls OSARGS 3,ch
    • =EOF#ch calls OSBYTE 127 on 8-bit systems, which vectors via FSCV. Otherwise, =EOF#ch calls OSARGS 5,ch.

    Special handles

    When reading PTR and EXT from 8-bit BASIC, the data parameter is BASIC's integer store, which will be set to the channel as the last item evaluated. That means that PTR#0 and EXT#0 pass a data value of zero; OSARGS 0,0 and OSARGS 2,0 do not change the data word; this means that in 8-bit BASICs PTR#0 and EXT#0 return zero, being the unchanged data word set to the channel.

    This means that other BASIC have the ability to use PTR#0 and EXT#0 to return information specific to that implementation. Some BASICs or operating systems allow other special handles to return specific information. Some operating systems allow BPUT#0 and BGET#0 to access the VDU and keyboard, so allow PTR#0, EXT#0 and EOF#0 to access keyboard or VDU information.

    See Special handles.

    Entry points

    • BBC BASIC Entry Address: &FFDA
    • 6502 Entry Address: &FFDA, vectors via &0214
    • Z80 Entry Address: &FFDA, vectors via &FFDB
    • 6809 Entry Address: &FFDA, vectors via &FFDB
    • 80x86 Entry Address: INT &44, vectors via 0000:0110
    • 32000 Entry Address: SVC &0C
    • PDP-11 Entry Address: EMT 8, vector &08
    • ARM Entry Address: SWI &09 "OS_Args", vector &09

    Implementations

    CFS

    Not implemented, simply returns with an RTS instruction.

    The Master 128 implements &00 fully, and &01 with a handle of 0.

    ROMFS

    Not implemented, simply returns with an RTS instruction.

    The Master 128 implements &00 fully, and &01 with a handle of 0.

    DFS

    Acorn DFS 0.xx and 1.xx implements &FF to &02. DFS 2.xx and later also implements &03.

    HDFS

    Andrew Duggan's Hierarchial DFS implements OSARGS &03,Y as 'Read allocated space' instead of 'Write extent'.

    Watford DFS

    Implements &FE to &02. OSARGS &FE preserves A, so the returned data has to be examined to see if the call has been acted on with code such as: 

       drive%=FNargs(&FE,-1)AND&FF

    drive% will be &FF if not supported, or the drive number if it is.

    NFS

    NFS 3.34 returns the command line address incorrectly. It points to the first non-'*' character of the command, not the first character of the parameters. NFS 3.60 and later return the command line address correctly. NFS 3.60 and later return A<>2 from OSARGS 2,0 to indicate this.

    ADFS

    HADFS

    Implements &FD to &06.

    Sprow ARM7 CoPro

    When reading the current filing system with OS_Args all three parameters must be zero, including the data parameter. SYS "OS_Args",0,0,data does not return the filing system number unless data is zero. The data parameter cannot be left set to a random value as it can when calling on other platforms. ARM BBC BASIC translates calls to &FFDA correctly setting R2 to zero.

    Jgharston 16:55, 6 November 2009 (UTC)
    Retrieved from "http://beebwiki.mdfs.net/index.php?title=OSARGS&oldid=3735"