OSARGS

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	Write filing system information	Return version and capabilities
&FE	Read filing system info/info on handle	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    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 Only 8-bit ANFS is known to implment this call. 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
&FD	Write filing system information. HADFS implements: 25: Currently Selected Directory 26: Currently Selected Library 27: User Root Directory
&FD	Read filing system information. HADFS implements: 25: Currently Selected Directory 26: Currently Selected Library 27: User Root Directory
&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	Return address of any parameters after a filename (command line tail). 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=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

Z88 allows:

• =EOF#-1 returns -1 for expanded, 0 for unexpanded
• =EXT#-1 returns the amount of free system memory
• =PTR#-1 returns the number of file handles still available in b16-b31 and the ROM version in b0-b15

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.

HADFS

Implements &FD to &06.

Jgharston 16:55, 6 November 2009 (UTC)