














                  M S X -- D O S   v e r s i o n  2
                  =================================












                  The advanced disk operating system

                         for MSX 2 computers


































CONTENTS                                       Page

1.    Introduction ............................  3
2.    List of functions .......................  4
3.    Function By Function Definitions ........  7
   3.1	 \
   . .    \  Definitions of each function
   . .    /
   3.90  /









   This  manual describes  in detail  the MSX-DOS  function calls provided by 
MSX-DOS version 2.20
























1.   INTRODUCTION

   This document describes in detail each of the MSX-DOS 2 function calls. It 
should  be read  in conjunction  with the  "Program Interface  specification" 
which describes  system features  such as  file handles,  fileinfo blocks and 
environment strings in general terms.


   There are  two ways  of doing  MSX-DOS function  calls, reflecting the two 
different  environments (MSX-DOS and disk BASIC) in which the system can run. 
Transient  programs  running  in  the  MSX-DOS  environment  must  access the 
functions with a "CALL 00005h" instruction. Disk BASIC and other MSX programs 
running  in  the disk  BASIC environment  (usually executing  from ROM)  must 
access the system via a "CALL 0F37Dh" instruction.

   There   are  some   limitations  when   calling  the  system  via  0F37Dh, 
particularly to do with error handling and abort routines. Also no parameters 
may be passed in page-1, unless they are in the master disk ROM (as they will 
be for  disk BASIC)  since the master disk ROM will be paged into page-1 when 
such  a function  call is  made. The individual function descriptions mention 
the differences for particular functions.


































2.   LIST OF FUNCTIONS

   Below there  is a  complete list  of the  functions calls. "CPM" indicates 
that the function is compatible with the equivalent CP/M 2.2 function, "MSX1" 
indicates  compatibility  with  MSX-DOS  version  1,  and  "NEW" indicates  a 
function  which is  new to  this system. An asterisk ("*") indicates that the 
function may  be safely  called from  a user disk error routine (see function 
64h and function 70h).


List of MSX-DOS 2 Function Calls

CPM MSX1  00h -  Program terminate
     CPM MSX1* 01h -  Console input
     CPM MSX1* 02h -  Console output
     CPM MSX1* 03h -  Auxiliary input
     CPM MSX1* 04h -  Auxiliary output
     CPM MSX1* 05h -  Printer output
     CPM MSX1* 06h -  Direct console I/O
         MSX1* 07h -  Direct console input
         MSX1* 08h -  Console input without echo
     CPM MSX1* 09h -  String output
     CPM MSX1* 0Ah -  Buffered line input
     CPM MSX1* 0Bh -  Console status


     CPM MSX1* 0Ch -  Return version number
     CPM MSX1  0Dh -  Disk reset
     CPM MSX1  0Eh -  Select disk


     CPM MSX1  0Fh -  Open file (FCB)
     CPM MSX1  10h -  Close file (FCB)
     CPM MSX1  11h -  Search for first entry (FCB)
     CPM MSX1  12h -  Search for next entry (FCB)
     CPM MSX1  13h -  Delete file (FCB)
     CPM MSX1  14h -  Sequential read (FCB)
     CPM MSX1  15h -  Sequential write FCB)
     CPM MSX1  16h -  Create file (FCB)
     CPM MSX1  17h -  Rename file (FCB)















     CPM MSX1* 18h -  Get login vector
     CPM MSX1* 19h -  Get current drive
     CPM MSX1  1Ah -  Set disk transfer address
         MSX1  1Bh -  Get allocation information
               1Ch -  Unused
               1Dh -  Unused
               1Eh -  Unused
               1Fh -  Unused
               20h -  Unused
     CPM MSX1  21h -  Random read (FCB)
     CPM MSX1  22h -  Random write(FCB)
     CPM MSX1  23h -  Get file size (FCB)
     CPM MSX1  24h -  Set random record (FCB)
               25h -  Unused
         MSX1  26h -  Random block write (FCB)
         MSX1  27h -  Random block read (FCB)
     CPM MSX1  28h -  Random write with zero fill (FCB)
               29h -  Unused
         MSX1* 2Ah -  Get date
         MSX1* 2Bh -  Set date
         MSX1* 2Ch -  Get time
         MSX1* 2Dh -  Set time
	 MSX1* 2Eh -  Set/reset verify flag
         MSX1* 2Fh -  Absolute sector read
         MSX1* 30h -  Absolute sector write
         NEW*  31h -  Get disk parameters


	    32h - \
            . .    \ Unused
            . .    /
            3Fh - /


    NEW     40h -  Find first entry
    NEW     41h -  Find next entry
    NEW     42h -  Find new entry


    NEW     43h -  Open file handle
    NEW     44h -  Create file handle
    NEW     45h -  Close file handle
    NEW     46h -  Ensure file handle
    NEW     47h -  Duplicate file handle
    NEW     48h -  Read from file handle
    NEW     49h -  Write to file handle
    NEW     4Ah -  Move file handle pointer 
    NEW     4Bh -  I/O control for devices
    NEW     4Ch -  Test file handle 

    NEW     4Dh -  Delete file or subdirectory
    NEW     4Eh -  Rename file or subdirectory
    NEW     4Fh -  Move file or subdirectory
    NEW     50h -  Get/set file attributes
    NEW     51h -  Get/set file date and time


    NEW     52h -  Delete file handle
    NEW     53h -  Rename file handle
    NEW     54h -  Move file handle
    NEW     55h -  Get/set file handle attributes
    NEW     56h -  Get/set file handle date and time


    NEW   * 57h -  Get disk transfer address
    NEW   * 58h -  Get verify flag setting
    NEW     59h -  Get current directory
    NEW     5Ah -  Change current directory
    NEW     5Bh -  Parse pathname
    NEW     5Ch -  Parse filename
    NEW   * 5Dh -  Check character
    NEW     5Eh -  Get whole path string
    NEW     5Fh -  Flush disk buffers


    NEW     60h -  Fork a child process
    NEW     61h -  Rejoin parent process
    NEW     62h -  Terminate with error code
    NEW     63h -  Define abort exit routine
    NEW     64h -  Define disk error handler routine
    NEW   * 65h -  Get previous error code
    NEW   * 66h -  Explain error code


    NEW     67h -  Format a disk
    NEW     68h -  Create or destroy RAM disk
    NEW     69h -  Allocate sector buffers
    NEW   * 6Ah -  Logical drive assignment


    NEW   * 6Bh -  Get environment item
    NEW   * 6Ch -  Set environment item
    NEW   * 6Dh -  Find environment item


    NEW   * 6Eh -  Get/set disk check status
    NEW   * 6Fh -  Get MSX-DOS version number
    NEW   * 70h -  Get/set redirection status












3.   FUNCTION BY FUNCTION DEFINITIONS

   Below are detailed descriptions of each of the MSX-DOS functions including 
both the  old and  new ones. The names in brackets after the function numbers 
are   the  public  labels  for  the  function  codes  which  are  defined  in 
"CODES.MAC". Programs should use these names whenever possible. 

   Many of  the functions below 40h return an error flag rather than an error 
code.  If the  error flag  is set  then the  actual error code indicating the 
cause of  the error can be obtained by the "get previous error code" function 
(function  65h).  All  of the  functions above  40h return  an error  code in 
register  A.  The  "Program Interface  Specification" document  describes the 
general  errors  which  can  be  returned  from  many of  the functions.  The 
individual  function specifications  here describe  the main error conditions 
which are specific to particular functions.
   Note that  many of  the function  calls which  modify the information on a 
disk  do  not  automatically  flush  disk  buffers  and  so  the disk  is not 
necessarily  correctly updated  immediately after  the function call is made. 
Such  calls  include  all  types  of  "create", "write",  "delete", "rename", 
"change file  attributes" and "change file date and time" function calls. The 
only  functions which  always flush disk buffers are "flush buffers", "close" 
and  "ensure".  After  these  operations the  disk will  always be  correctly 
updated.




  3.1   PROGRAM TERMINATE (00H)

     Parameters:    C = 00H (_TERM0)
     Results:       Does not return



   This function  terminates program  with a zero return code. It is provided 
for  compatibility with MSX-DOS 1 and CP/M, the preferred method of exiting a 
program is  to use  the "terminate  with error  code" function call (function 
62h),  passing  a  zero  error  code  if  that is  what is  desired. See  the 
description   of  that   function  call,  and  also  the  "Program  Interface 
Specification", for  details of  what happens when a program terminates. This 
function call never returns to the caller.














  3.2   CONSOLE INPUT (01H)

    Parameters:    C = 01H (_CONIN)
    Results:     L=A = Character from keyboard



   A  character will be read from the standard input (file handle 0 - usually 
the keyboard)  and echoed to the standard output (file handle 1 - usually the 
screen).  If no  character is  ready then  this function  will wait  for one. 
Various control  characters, as  specified for  the "console status" function 
(function  0Bh),  will  be  trapped  by  this  function  for  various control 
purposes.  If one  of these  characters is detected then it will be processed 
and this function will wait for another character. Thus these characters will 
never be returned to the user by this function.




  3.3   CONSOLE OUTPUT (02H)

     Parameters:    C = 02H (_CONOUT)
                    E = Character to be output
     Results:       None


   The character passed in register E is written to the standard output (file 
handle 1 - usually the screen). If printer echo is enabled then the character 
is also  written to  the printer.  Various control codes and escape sequences 
are  interpreted as  screen control codes. A list of these is included in the 
"Program Interface  Specification", they  are a sub-set of the standard VT-52 
control codes. TABs will be expanded to every eighth column.



   A  console input  status check  is done, and if any of the special control 
characters  described  for the  "console status"  function (function  0Bh) is 
found then  it will  be processed  as for  that function. Any other character 
will be saved internally for a later "console input" function call.



  3.4   AUXILIARY INPUT (03H)

     Parameters:    C = 03H (_AUXIN)
     Results:     L=A = Input character



   A character is read from the auxiliary input device (file handle 3) and if 
no character  is ready  then it will wait for one. The auxiliary input device 
must  have been installed before this function may be used. If no such device 
has been  installed then  this function  will always  return the  end of file 
character ("Ctrl-Z").

  3.5   AUXILIARY OUTPUT (04H)

     Parameters:    C = 04H (_AUXOUT)
                   E = Character to be output
     Results:       None



   The character passed in register E will be written to the auxiliary output 
device (file  handle 3). The auxiliary output device must have been installed 
before  this function  may be used. If no such device has been installed then 
this function will simply throw the character away.




  3.6   PRINTER OUTPUT (05H)

     Parameters:    C = 05H (_LSTOUT)
                   E = Character to be output
      Results:       None



   The character  passed in  register E  will be sent to the standard printer 
device  (file handle  4 -  usually the parallel printer). The same channel is 
used for console output which is echoed to the printer. TABs are not expanded 
by this  function, although they are expanded when screen output is echoed to 
the printer with "Ctrl-P".




  3.7   DIRECT CONSOLE I/O (06H)

     Parameters:    C = 06H (_DIRIO)
                    E = 00H...FEH - character for output
                      = FFH  - requests input
     Results:     A=L = input - 00H - no character ready
                                else input character
                       undefined for output


   If  E=FFh on  entry then the keyboard will be examined for a characterfrom 
the standard input (file handle 0) and 00h returned if no character is ready. 
If a  character is  ready then  it will be read from the standard input (file 
handle  0) and  returned in register A without being echoed and with no check 
for control characters.


   If  E<>FFh  on entry  then the  character in  register E  will be  printed 
directly to  the standard  output (file  handle 1)  with no  TAB expansion or 
printer  echo. Also  no console  status check  is done by this function. Note 
that although  this function  does not  expand TABs,  the VT-52 control codes 
include TAB expansion so the effect on the screen is the same.


  3.8   DIRECT CONSOLE INPUT (07H)

     Parameters:    C = 07H (_DIRIN)
     Results:     L=A = Input character



   This function  is identical  to the  input option  of function 06h, except 
that  if no  character is  ready it  will wait for one. Like function 06h, no 
echo  or  control  characters  checks  will  be  done.  This function  is not 
compatible with CP/M which uses this function number for "get I/O byte".




  3.9   CONSOLE INPUT WITHOUT ECHO (08H)

     Parameters:    C = 08H (_INNOE)
     Results:     L=A = Input character



   This function is identical to function 01h except that the input character 
will  not be echoed to the standard output. The same control character checks 
will be  done. This  function is  not compatible  with CP/M  which uses  this 
function number for "set I/O byte".




  3.10   STRING OUTPUT (09H)

     Parameters:    C = 09H (_STROUT)
                  DE = Address of string
     Results:       None



   The characters  of the  string pointed  to by  register DE  will be output 
using  the normal  console output  routine (function call 02h). The string is 
terminated by "$" (ASCII 24h).












  3.11   BUFFERED LINE INPUT (0AH)

     Parameters:    C = 0AH (_BUFIN)
                   DE = Address of an input buffer
     Results:       None


   DE  must point  to a  buffer to  be used for input. The first byte of this 
buffer  must  contain  the  number of  characters which  the buffer  can hold 
(0...255). A  line of input will be read from the standard input device (file 
handle  0 - usually the keyboard) and stored in the buffer. The input will be 
terminated  when  a  CR  is  read  from  the  standard input.  The number  of 
characters entered,  which does  not include the CR itself, will be stored at 
(DE+1).  If there  is room in the buffer then the CR will be stored after the 
last character.



   When inputting  from the  keyboard (which  will normally  be the  case), a 
simple  line  editor  is provided,  and also  a 256  byte circular  buffer of 
previous  lines which  can be  edited and  re-entered. The  details of  these 
editing  facilities  are described  in the  separate "Command  Specification" 
document, so  they are not included here. When the input buffer becomes full, 
the console bell will be rung for each character typed which cannot be put in 
the  buffer. Each character entered will be echoed to the standard output and 
also to the printer if printer echo is enabled.




  3.12   CONSOLE STATUS (0BH)

     Parameters:    C = 0BH (_CONST)
     Results:     L=A = 00H if no key was pressed
                      = FFH if a key was pressed


   A  flag is returned in register A to indicate whether a character is ready 
(that is,  a key  was pressed) for input from the keyboard. If a character is 
ready then it will be read and tested for certain special control characters. 
If it is not one of these then it is stored in an internal single byte buffer 
and   subsequent  call   to  this  function  will  return  "character  ready" 
immediately  without  checking the  keyboard. If  this function  says that  a 
character is ready then the character may be read by function 02h or 08h.


   If the  character is  "Ctrl-C" then  the program will be terminated with a 
".CTRLC"  error  via  the  user's  abort routine  if one  is defined.  If the 
character  is  "Ctrl-P"  then printer  echo will  be enabled  and it  will be 
disabled  if it  is "Ctrl-N".  If the  character is "Ctrl-S" then the routine 
will hang  up waiting for another character to be pressed and then return "no 
character  ready", thus  providing a  "wait" facility. The character typed to 
continue operation  will be  ignored, except  that of it is "Ctrl-C" then the 
program  will  be  terminated.  These  same input  checks are  also done  for 
functions 01h, 02h, 08h, 09h and 0Ah.


  3.13   RETURN VERSION NUMBER (0CH)

     Parameters:    C = 0CH (_CPMVER)
     Results:     L=A = 22H
                 H=B = 00H 



   This  function  simply  returns  the  CP/M version  number which  is being 
emulated. This is always version 2.2 in current systems. 


  3.14   DISK RESET (0DH)

     Parameters:    C = 0DH (_DSKRST)
     Results:       None



   Any  data which  is waiting in internal buffers is written out to disk. It 
is not  necessary to call this function in order to allow a disk change as is 
the case with CP/M. The disk transfer address is also set back to its default 
value of 80h by this function.




  3.15   SELECT DISK (0EH)

     Parameters:    C = 0EH (_SELDSK)
                    E = Drive number.  0=A:  1=B:   etc.
     Results:     L=A = Number of drives (1...8)


   This function simply selects the specified drive as the default drive. The 
current  drive is  also stored  at address  0004h for CP/M compatibility. The 
number  of  drives available  is returned  in register  A but  this will  not 
include the RAM disk.















  3.16   OPEN FILE [FCB] (0FH)

     Parameters:    C = 0FH (_FOPEN)
                   DE = Pointer to unopened FCB 
     Results:     L=A = 0FFH if file not found
                           =   0  if file is found


   The unopened  FCB must  contain a  drive which may be zero to indicate the 
current  drive  and  a filename  and extension  which may  be ambiguous.  The 
current directory of the specified drive will be searched for a matching file 
and if found it will be opened. Matching entries which are sub-directories or 
system files will be ignored, and if the filename is ambiguous then the first 
suitable matching entry will be opened.


   Device  names may  be put in the FCB (without a colon) to allow devices to 
be accessed  as if  they were  actually disk files. The standard device names 
are defined in the "Program Interface Specification".


   The  low byte  of the extent number is not altered by this function, and a 
file will only be opened if it is big enough to contain the specified extent. 
Normally the  transient program  will set  the extent  number to  zero before 
calling this function. The high byte of the extent number will be set to zero 
to ensure compatibility with CP/M.


   The filename  and extension in the FCB will be replaced by the actual name 
of  the file  opened from the directory entry. This will normally be the same 
as what was there before but may be different if an ambiguous filename or one 
with lower case letters in was used. 

   The  record count  will be  set to  the number  of 128 byte records in the 
specified extent, which is calculated from the file size. The file size field 
itself, the  volume-id and  the 8  reserved bytes  will also  be set  up. The 
current record and random record fields will not be altered by this function, 
it  is the  application program's  responsibility to  initialize them  before 
using the read or write functions.



   If  the file  cannot be  found, then the "APPEND" environment item will be 
examined. If  this is set then it is interpreted as a drive/path string which 
specifies  a second  directory in  which to  look for the file. The specified 
directory will  be searched  for the  file and  if found it will be opened as 
above.  In this  case the  drive byte  of the FCB will be set to the drive on 
which the  file was  found to  ensure correct  accessing of  the file  if the 
original drive byte was zero (default).






  3.17   CLOSE FILE [FCB] (10H)

     Parameters:    C = 10H (_FCLOSE)
                   DE = Pointer to opened FCB
     Results:     L=A = 0FFH if not successful
                     =   0  if successful



   The  FCB must  have previously been opened with either an OPEN or a CREATE 
function  call.  If  the  file has  only been  read then  this function  does 
nothing. If  the file  has been  written to  then any  buffered data  will be 
written  to disk  and the directory entry updated appropriately. The file may 
still be  accessed after a close, so the function can be regarded as doing an 
"ensure" function.




  3.18   SEARCH FOR FIRST [FCB] (11H)

     Parameters:    C = 11H (_SFIRST)
                   DE = Pointer to unopened FCB
     Results:     L=A = 0FFH if file not found
                     =   0  if file found.
 

   This function searches the current directory of the drive specified in the 
FCB  (default  drive  if  FCB contains  zero) for  a file  which matches  the 
filename and  extension in the FCB. The filename may be ambiguous (containing 
"?"  characters) in which case the first match will be found. The low byte of 
the extent  field will  be used,  and a  file will only be found if it is big 
enough  to contain  this extent number. Normally the extent field will be set 
to  zero  by  the  program  before  calling  this  function. System  file and 
sub-directory entries will not be found.


   If a suitable match is found (A=0) then the directory entry will be copied 
to the  DTA address,  preceded by the drive number. This can be used directly 
as an FCB for an OPEN function call if desired. The extent number will be set 
to  the low byte of the extent from the search FCB, and the record count will 
be initialized  appropriately (as  for OPEN).  The attributes  byte from  the 
directory  entry will  be stored  in the  S1 byte  position, since its normal 
position (immediately  after the  filename extension  field) is  used for the 
extent byte.


   If no match is found (A=0FFh) then the DTA will not be altered. In no case 
will  the FCB  pointed to  by DE  be modified at all. This function remembers 
sufficient information  internally to  allow it to continue the search with a 
SEARCH  FOR NEXT function, so it is not necessary for the FCB to be preserved 
if doing a SEARCH FOR NEXT function.



   In CP/M,  if the  drive number  is set  to "?"  in this  function then all 
directory  entries, allocated  or free  will be  matched. Also  if the extent 
field is  set to "?" then any extent of a file will be matched. Both of these 
features  are normally  only used  by special purpose CP/M programs which are 
generally  specific  to  the  CP/M filing  system (such  as "STAT").  Neither 
feature is present in MSX-DOS 1/2.




  3.19   SEARCH FOR NEXT [FCB] (12H)

     Parameters:    C = 12H (_SNEXT)
     Results:     L=A = 0FFH if file not found
                     =   0  if file found.



   It continues  the search to look for the next match with the filename. The 
results returned from this function are identical to SEARCH FOR FIRST and all 
the  same comments apply. The information used to continue the search is held 
internally within  MSX-DOS and  so the  original FCB  used in  the SEARCH FOR 
FIRST need not still exist.




  3.20   DELETE FILE [FCB] (13H)

     Parameters:    C = 13H (_FDEL)
                  DE = Pointer to unopened FCB
     Results:     L=A = 0FFH if no files deleted
                      =   0  if files deleted OK



   All  files in  the current directory of the disk specified by the FCB, and 
which match  the ambiguous filename in the FCB, are deleted. Sub-directories, 
system  files, hidden files and read only files are not deleted. If any files 
at all are successfully deleted then this function returns with A=0. A return 
with A=FFh indicates that no files were deleted.














  3.21   SEQUENTIAL READ [FCB] (14H)

     Parameters:    C = 14H (_RDSEQ)
                   DE = Pointer to opened FCB
     Results:     L=A = 01H if error (end of file)
                      =  0  if read was successful


   This function reads the next sequential 128 byte record from the file into 
the  current  disk transfer  address. The  record is  defined by  the current 
extent  (high  and  low  bytes) and  the current  record. After  successfully 
reading the  record, this  function increments  the current  record and if it 
reaches  080h, sets  it back  to zero  and increments  the extent number. The 
record count field is also kept updated when necessary.



   Unlike  CP/M it  is possible  to have  partially filled records, since the 
file size is not necessarily a multiple of 128 bytes. If this occurs then the 
partial record  is padded  out with zeroes when it is copied to the transient 
program's DTA address.




  3.22   SEQUENTIAL WRITE [FCB] (15H)

     Parameters:    C = 15H (_WRSEQ)
                   DE = Pointer to opened FCB
     Results:     L=A = 01H if error (disk full)
		      =  0  if write was successful



   This function  writes the 128 bytes from the current disk transfer address 
to  the file  at the position defined by the current record and extent, which 
are then  incremented appropriately.  The record  count byte  is kept updated 
correctly  if the  file is  extended or if the write moves into a new extent. 
The file size in the FCB is also updated if the file is extended. 


  3.23   CREATE FILE [FCB] (16H)

     Parameters:    C = 16H (_FMAKE)
                   DE = Pointer to unopened FCB
     Results:     L=A = 0FFH if unsuccessful
                      =   0  if successful   


   This function creates a new file in the current directory of the specified 
drive and opens it ready for reading and writing. The drive, filename and low 
byte of the extent number must be set up in the FCB and the filename must not 
be  ambiguous. Checks  will be  done to ensure that invalid filenames are not 
created.

   If there is already a file of the required name then the action depends on 
the value  of the  extent number byte. Normally this will be zero and in this 
case  the old  file will  be deleted  and a  new one  created. However if the 
extent  number  is non-zero  then the  existing file  will be  opened without 
creating a  new file.  This ensures compatibility with early versions of CP/M 
where each extent had to be explicitly created.



   In all  cases the  resulting file  will be opened with the required extent 
number exactly as if an OPEN function call had been done.




  3.24   RENAME FILE [FCB] (17H)

     Parameters:    C = 17H (_FREN)
                   DE = Pointer to unopened FCB
     Results:     L=A = 0FFH not if successful
		      =   0  if successful 


   The  unopened FCB  has the  normal drive  and filename,  and also a second 
filename starting  at (DE+17).  Every file  in the  current directory  of the 
specified  drive which  matches the  first filename, is changed to the second 
filename with  "?" characters  in the second filename leaving the appropriate 
character  unchanged.  Checks  are  done  to  prevent  duplicate  or  illegal 
filenames  from being  created. Entries for sub-directories, hidden files and 
system files will not be renamed. 




  3.25   GET LOGIN VECTOR (18H)

     Parameters:    C = 18H (_LOGIN)
     Results:      HL = Login vector



   This function  returns a  bit set in HL for each drive which is available, 
bit-0 of L corresponding to drive "A:". Up to eight drives ("A:" to "H:") are 
supported  by the  system currently,  so register  H will  usually be zero on 
return.




  3.26   GET CURRENT DRIVE (19H)

     Parameters:    C = 19H (_CURDRV)
     Results:     L=A = Current drive (0=A: etc)

   This function just returns the current drive number.



  3.27   SET DISK TRANSFER ADDRESS (1AH)

     Parameters:    C = 1AH (_SETDTA)
                   DE = Required Disk Transfer Address
     Results:       None



   This function simply records the address passed in DE as the disk transfer 
address.  This address  will be  used for  all subsequent  FCB read and write 
calls,  for  "search for  first" and  "search for  next" calls  to store  the 
directory entry, and for absolute read and write calls. It is not used by the 
new MSX-DOS  read and  write functions.  The address  is set back to 80h by a 
DISK RESET call.




  3.28   GET ALLOCATION INFORMATION (1BH)

     Parameters:    C = 1BH (_ALLOC)
                    E = Drive number (0=current, 1=A: etc)
     Results:       A = Sectors per cluster
                   BC = Sector size (always 512)
                   DE = Total clusters on disk
                   HL = Free clusters on disk
                   IX = Pointer to DPB
                   IY = Pointer to first FAT sector  


   This function  returns various information about the disk in the specified 
drive.  It is  not compatible  with CP/M  which uses  this function number to 
return the  address of an allocation vector. Note that unlike MSX-DOS 1, only 
the  first sector  of the FAT may be accessed from the address in IY, and the 
data there will only remain valid until the next MSX-DOS call.

















  3.29   RANDOM READ [FCB] (21H)

     Parameters:    C = 21H (_RDRND)
                   DE = Pointer to opened FCB
     Results:     L=A = 01H if error (end of file)
			 0  if read was successful


   This function  reads a  128 byte  record from the file to the current disk 
transfer  address. The  file position  is defined  by the  three byte  random 
record number  in the  FCB (bytes  21h...23h). Unlike CP/M all three bytes of 
the  random record  number are  used. A partial record at the end of the file 
will be padded with zeroes before being copied to the user's DTA.


   The  random  record  number is  not altered  so successive  calls to  this 
function  will read  the same  record unless the transient program alters the 
random record number. A side effect is that the current record and extent are 
set up  to refer  to the  same record as the random record number. This means 
that  sequential reads  (or writes)  can follow  a random read and will start 
from the  same record. The record count byte is also set up correctly for the 
extent.




  3.30   RANDOM WRITE [FCB] (22H)

     Parameters:    C = 22H (_WRRND)
                   DE = Pointer to opened FCB
     Results:     L=A = 01H if error (disk full)
		      =  0  if no error 


   This  function writes  a 128  byte record  from the  current disk transfer 
address to  the file,  at the  record position  specified by  the three  byte 
random  record number (bytes 21h...23h). All three bytes of the random record 
number are  used. If  the record  position is  beyond the current end of file 
then un-initialized disk space will be allocated to fill the gap.



   The random record number field will not be changed, but the current record 
and extent  fields will  be set  up to  refer to  the same record. The record 
count  byte will be adjusted as necessary if the file is being extended or if 
the write goes into a new extent. 









  3.31   GET FILE SIZE [FCB] (23H)

     Parameters:    C = 23H (_FSIZE)
                   DE = Pointer to unopened FCB
     Results:     L=A = 0FFH if file not found
		      =   0  if file found OK



   This function  searches for  the first match with the filename in the FCB, 
exactly the same as OPEN FILE (function 0FH). The size of the located file is 
rounded up to the nearest 128 bytes and the number of records determined. The 
three byte random record field of the FCB is set to the number of records, so 
it is the number of the first record which does not exist. The fourth byte of 
the random record number is not altered.




  3.32   SET RANDOM RECORD [FCB] (24H)

     Parameters:    C = 24H (_SETRND)
                   DE = Pointer to opened FCB
     Results:	   None



   This function simply sets the three byte random record field in the FCB to 
the record  determined by  the current  record and  extent number. The fourth 
byte  of the  random record  number is  not altered.  No check  is done as to 
whether the record actually exists in the file.




  3.33   RANDOM BLOCK WRITE [FCB] (26H)

     Parameters:    C = 26H (_WRBLK)
                   DE = Pointer to opened FCB
                   HL = Number of records to write
     Results:	    A = 01H if error
                      =  0  if no error


   Data  is written from the current disk transfer address to the position in 
the file  defined by  the random record number. The record size is determined 
by  the record size field in the FCB (bytes 0Eh and 0Fh) which must be set by 
the user  after opening  the file  and before  calling this  function. If the 
record  size is  less than  64 bytes then all four bytes of the random record 
number are used, otherwise only the first three are used.

   The number  of records to be written is specified by HL, and together with 
the  record size  this determines  the amount of data to be written. An error 
will be returned if the size exceeds 64k, thus limiting the maximum size of a 
transfer.


   After  writing the  data, the  random record field is adjusted to the next 
record number  in the file (ie. HL is added on to it). The current record and 
extent  fields are not used or altered. The file size field is updated if the 
file has been extended.




   The  record size  can be any value from 1...0FFFFh. Small record sizes are 
no less  efficient that  large record sizes so if desired the record size can 
be set to one and the record count then becomes a byte count. It is desirable 
to  write as much as possible with one function call since one large transfer 
will be quicker than several small ones.


   If  the number  of records  to write  (HL) is  zero then  no data  will be 
written, but  the size  of the file will be altered to the value specified by 
the random record field. This may be either longer or shorter than the file's 
current  size  and  disk  space  will  be  allocated  or  freed as  required. 
Additional  disk space  allocated in  this way will not be initialized to any 
particular value.




  3.34   RANDOM BLOCK READ [FCB] (27H)

     Parameters:    C = 27H (_RDBLK)
                   DE = Pointer to opened FCB
                   HL = Number of records to read
     Results:       A = 01H if error (usually caused by end-of-file)
                      =  0  if no error
                   HL = Number of records actually read


This  function is  the complement of the BLOCK WRITE function described above 
and most of the same comments apply as regards its use. Again if large blocks 
are read then it will be much faster than the normal CP/M operation.
   For example if it is desired to read 20k from a file, it is better to read 
the 20k  with one  function call rather than 20 separate function calls of 1k 
each.  However it  makes no  difference whether  the 20k  read is done with a 
record size  of 1  and a record count of 20k, with a record size of 20k and a 
record count of 1, or any intermediate combination.




   The number of records actually read is returned in HL. This may be smaller 
than the  number of records requested if the end of the file was encountered. 
In  this case  any partial record will be padded out with zeroes before being 
copied to  the users  DTA. The  random record  field is adjusted to the first 
record not read, ie. the value returned in HL is added on to it.



  3.35   RANDOM WRITE WITH ZERO FILL [FCB] (28H)

     Parameters:    C = 28H (_WRZER)
                   DE = Pointer to opened FCB
     Results:     L=A = 01H if error
		      = 00H if no error


   This  function is  identical to RANDOM WRITE (function 22h) except that if 
the file has to be extended, any extra allocated disk clusters will be filled 
with zeroes before writing the data. 





  3.36   GET DATE (2AH)

     Parameters:    C = 2AH (_GDATE)
     Results:      HL = Year 1980...2079
                   D = Month (1=Jan...12=Dec)
                   E = Date (1...31)
		   A = Day of week (0=Sun...6=Sat)

   This function simply returns the current value of the internal calender in 
the format shown.





  3.37   SET DATE (2BH)

     Parameters:    C = 2BH (_SDATE)
                   HL = Year 1980...2079
                   D = Month (1=Jan...12=Dec)
                   E = Date (1...31)
     Results:      A = 00H if date was valid
                       FFH if date was invalid


   The supplied  date is  checked for  validity and if it is valid then it is 
stored  as the  new date.  The validity  checks include full checking for the 
number of  days in each month and leap years. If the date is invalid then the 
current  date will  be left  unaltered. The  date is  stored in the real time 
clock chip so it will be remembered when the machine is turned off.







  3.38   GET TIME (2CH)

     Parameters:    C = 2CH (_GTIME)
     Results:       H = Hours (0...23)
                    L = Minutes (0...59)
                    D = Seconds (0...59)
                    E = Centiseconds (always zero)

   This function  returns the current value of the system clock in the format 
shown.





  3.39   SET TIME (2DH)

     Parameters:    C = 2DH (_STIME)
                    H = Hours (0...23)
                    L = Minutes (0...59)
                    D = Seconds (0...59)
                    E = Centiseconds (ignored)
     Results:       A = 00H if time was valid
                        FFH if time was invalid


   This function  sets the internal system clock to the specified time value. 
If  the time  is invalid then register A will be returned as 0FFh to indicate 
an error  and the  current time will be left unaltered. The time is stored in 
the  real time  clock chip and so it will be remembered and kept correct when 
the machine is turned off.





  3.40   SET/RESET VERIFY FLAG (2EH)

     Parameters:    C = 2EH (_VERIFY)
                    E =  0 to disable verify
		      <> 0 to enable verify
     Results:       None

   This function  simply enables  or disables  automatic verification  of all 
writes.  It  defaults  to off  when MSX-DOS  is started  up. Enabling  verify 
improves  system reliability  but also slows down write operations. Note that 
this function  depends on  the disk  driver and  the verification will not be 
done if the driver does not support it.







  3.41   ABSOLUTE SECTOR READ (2FH)

     Parameters:    C = 2FH (_RDABS)
                   DE = Sector number
                    L = Drive number (0=A: etc.)
                    H = Number of sectors to read
     Results:       A = Error code (0=> no error)



   This function  reads sectors  directly from  the disk without interpreting 
them  as files.  The disk  must be  a valid  DOS disk in order for the sector 
number to  be translated  into a  physical position  on the disk. The sectors 
will  be read  to the  current disk  transfer address. Any disk error will be 
reported by the system in the usual way.

 


  3.42   ABSOLUTE SECTOR WRITE (30H)

     Parameters:    C = 30H (_WRABS)
                   DE = Sector number
                    L = Drive number (0=A: etc.)
                    H = Number of sectors to write
     Results:       A = Error code



   This  function writes  sectors directly  to the  disk without interpreting 
them as  files. The  disk must  be a  valid DOS  disk in order for the sector 
number  to be  translated into  a physical  position on the disk. The sectors 
will be  written from  the current disk transfer address. Any disk errors are 
reported by the system in the usual way.





















  3.43   GET DISK PARAMETERS (31H)

     Parameters:    C = 31H (_DPARM)
                   DE = Pointer to 32 byte buffer
                    L = Drive number (0=default, 1=A: etc.)
     Results:       A = Error code
                   DE = Preserved


   This functions  returns a  series of  parameters relating to the format of 
the  disk in  the specified  drive, to the buffer allocated within the user's 
program. It  is useful  for programs  which are  going to  do absolute sector 
reads  and writes,  in order  for them  to be  able to interpret the absolute 
sector numbers. The parameters returned contain some redundant information in 
order to  provide parameters which are most useful to transient programs. The 
format of the returned parameter block is:


     DE+0      - Physical drive number (1=A: etc)
     DE+1,2    - Sector size (always 512 currently)
     DE+3      - Sectors per cluster (non-zero power of 2)
     DE+4,5    - Number of reserved sectors (usually 1)
     DE+6      - Number of copies of the FAT (usually 2)
     DE+7,8    - Number of root directory entries
     DE+9,10   - Total number of logical sectors
     DE+11     - Media descriptor byte
     DE+12     - Number of sectors per FAT
     DE+13..14 - First root directory sector number
     DE+15..16 - First data sector number
     DE+17..18 - Maximum cluster number
     DE+19     - Dirty disk flag
     DE+20..23 - Volume id. (-1 => no volume id.)
     DE+24..31 - Reserved (currently always zero)

   The dirty  disk flag  indicates whether  in the disk there is a file which 
can  be recovered  by UNDEL  command. It is reset when the file allocation is 
done.


















  3.44   FIND FIRST ENTRY (40H)

     Parameters:    C = 40H (_FFIRST)
                   DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
                        HL = filename ASCIIZ string (only if
                                DE = fileinfo pointer)
                         B = Search attributes
                   IX = Pointer to new fileinfo block
     Results:       A = Error
		 (IX) = Filled in with matching entry


   The "drive/path" portion of the string, or the fileinfo block, specifies a 
directory which  is to  be searched.  A ".IATTR"  error will be returned if a 
fileinfo  block which  specifies a  file is passed. The "file" portion of the 
string, or  the filename  ASCIIZ string in HL, determines what filenames will 
be matched. If no match is found then a ".NOFIL" error is returned, otherwise 
the  fileinfo block  pointed to  by IX  is filled  in with the details of the 
matching entry.


   The filename  may contain  ambiguous filename  characters ("?"  or "*") in 
which case the first matching entry will be returned. If the filename is null 
(either  the ASCIIZ  string pointed  to by DE is null or ends in a "\" or the 
filename string  pointed to  by HL  is null),  then this function will behave 
exactly as if the filename was "*.*" so any name will match.


   The  attributes byte  in register  B specifies  what type of entry will be 
matched. If  it is zero then only non-hidden, non-system files will be found. 
If  the directory,  hidden or  system bits in register B are set then entries 
with these  attributes will  be matched  as well  as ordinary files. The read 
only and archive bits of register B are ignored.


   If the  volume name bit of register B is set then the search is exclusive, 
only  the volume  label entry  will be  found. In this case also the fileinfo 
block  and  filename or  the drive/path/file  string are  ignored apart  from 
specifying the drive. This means that the volume name will always be found in 
the root directory if it exists whether or not it matches the filename given.



   If DE  points to  a fileinfo  block, then  if desired, IX can point to the 
same  fileinfo block.  In this  case when  a match  is found the new fileinfo 
block will overwrite the old one.








  3.45   FIND NEXT ENTRY (41H)

     Parameters:    C = 41H (_FNEXT)
                        IX = Pointer to fileinfo block from
			     previous find first function.
     Results:       A = Error
		 (IX) = Filled in with next matching entry



   This function  should only  be used  after a  "find first  entry" function 
call.  It  searches  the  directory  for the  next match  to the  (presumably 
ambiguous)  filename which was given to the "find first entry" function call. 
If there  are no  more matching  entries then  a ".NOFIL"  error is returned, 
otherwise  the fileinfo block is filled in with the information about the new 
matching entry.




  3.46   FIND NEW ENTRY (42H)

     Parameters:    C = 42H (_FNEW)
                        DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
                        HL = filename ASCIIZ string (only if
                                DE = fileinfo pointer)
                         B = b0..b6 = Required attributes
                             b7 = Create new flag
                   IX = Pointer to new fileinfo block
                         containing template filename
     Results:       A = Error
		 (IX) = Filled in with new entry


   This function is very similar to the "find first entry" function described 
above. The  parameters in  HL and  DE are  used in  exactly the  same way  to 
specify  a  directory  entry.  However  instead  of  searching  the  selected 
directory  for an entry which matches the specified name, a new entry will be 
created with this name. The fileinfo block pointed to by IX will be filled in 
with information  about the  new entry  just as  if it  had been found with a 
"find first entry" call.


   If there  are any  ambiguous characters ("?" or "*") in the filename, then 
they will be replaced by the appropriate character from a "template filename" 
in  the filename  position of the new fileinfo block pointed to by IX. If the 
result is  still ambiguous,  or otherwise  illegal, then  a ".IFNM"  error is 
returned. This is useful for copy operations which do an automatic rename.
 

   Like  "find first entry", if the filename is null, then it will be treated 
exactly as  if it  was "*.*".  For this function that means that the template 
filename will be used as the new filename to create.

   A  ".DRFUL"  error  will  be  returned if  there is  no room  in the  root 
directory, and a ".DKFUL" if a sub-directory must be extended and the disk is 
already full.


   The  attribute byte  passed in  register B  is the attribute which the new 
entry will be given. If the volume name bit is set then a volume name will be 
created in  the root  directory. If  the directory  bit is set then the entry 
created  will be  for a  sub-directory, otherwise  it will be for a file. The 
system, hidden  and read  only bits may be set for a file, and the hidden bit 
for a sub-directory. A file will always be created with the archive attribute 
bit set.


   A file  will be  created as  zero length with the current date and time. A 
sub-directory will have a single cluster allocated to it and the "." and ".." 
entries will be initialized appropriately.


   If there is already an entry with the specified name in the directory then 
the action depends on the "create new" flag (bit-7 of register B) and also on 
the type  of the entry. If the "create new" flag is set then a ".FILEX" error 
will  always be returned. Setting this flag thereforeensures that an existing 
file will not be deleted.


   If  an entry  already exists and the "create new" flag is not set then the 
type of  the existing  entry is  examined to see whether it can be deleted to 
make  room for the new file. An error will be returned if the entry is a read 
only file  (".FILRO" error), a system file (".SYSX" error) or a sub-directory 
(".DIRX" error) or there is a file handle already open to this file (".FOPEN" 
error). If we are trying to create a sub-directory then even an ordinary file 
will not be deleted (".FILEX" error).


   For  all  of  these  error  codes (".FILEX",  ".FILRO", ".SYSX",  ".DIRX", 
".FOPEN"),  the  fileinfo  block will  be filed  in with  the details  of the 
already  existing entry  and this fileinfo block may be used exactly as if it 
had been returned from a "find first" function.
















  3.47   OPEN FILE HANDLE (43H)

     Parameters:    C = 43H (_OPEN)
                   DE = Drive/path/file ASCIIZ string
                            or fileinfo block pointer
                    A = Open mode. b0 set => no write
                                   b1 set => no read
				   b2 set => inheritable
                                   b3..b7   -  must be clear
     Results:       A = Error
		    B = New file handle


   The  drive/path/file string or the fileinfo block should normally refer to 
a file  rather than  a sub-directory  or volume  name. If it is a volume name 
then a ".IATTR" error will be returned. If it is a sub-directory then ".DIRX" 
error will be returned.


   Assuming that a file is specified then it will be opened ready for reading 
and/or writing (depending on the open mode in A) and a new file handle for it 
will  be returned in register B. The lowest available file handle number will 
be used and an error will result if there are no spare file handles (".NHAND" 
error), or insufficient memory (".NORAM" error).


   If the  "no read" bit of register A is set then reads from the file handle 
will  be  rejected  and if  the "no  write" bit  is set  then writes  will be 
rejected,  in both  cases with an ".ACCV" error. Writes will also be rejected 
if  the  file is  read only  (".FILRO" error).  If the  "inheritable" bit  of 
register A  is set  then the  file handle  will be inherited by a new process 
created by the "fork" function call (see function 60h).



   If a  device file  handle is opened by giving a filename which matches one 
of  the built in devices (for example "CON" or "NUL"), then it will always be 
opened initially in ASCII mode. The IOCTL function (function 4Bh) can be used 
to change  this to  binary mode  but great care must be taken in reading from 
devices in binary mode because there is no end of file condition.















  3.48   CREATE FILE HANDLE (44H)

     Parameters:    C = 44H (_CREATE) 
                   DE = Drive/path/file ASCIIZ string
                    A = Open mode. b0 set => no write
                                   b1 set => no read
				   b2 set => inheritable
                                 b3..b7   -  must be clear
                    B = b0..b6 = Required attributes
                            b7 = Create new flag
     Results:       A = Error
		    B = New file handle


   A file  or sub-directory,  as specified  by the  attributes in register B, 
will  be  created  with  the  name  and  in  the  directory specified  by the 
drive/path/file  string. A ".IATTR" error is returned if register B specifies 
a volume name.


   An error  will be returned if the file or sub-directory cannot be created. 
The  error conditions  in this  case are the same as for the "find new entry" 
function (function  42h) with  the main  error codes being ".FILEX", ".DIRX", 
".SYSX",  ".FILRO",  ".FOPEN",  ".DRFUL" and  ".DKFUL". Like  the "find  new" 
function,  if the  "create new"  flag (bit-7  of register  B) is  set then an 
existing file will not be deleted and will always return a ".FILEX" error.


   If the  attributes byte  specifies a sub-directory then the hidden bit may 
also  be set to create a hidden sub-directory. For a file, the hidden, system 
or  read  only  bits  may  be  set  to  create  a  file with  the appropriate 
attributes. An  invalid attributes  bits will  simply be ignored. A file will 
always be created with the archive attribute bit set.



   A  file  will  automatically  be opened  just as  for the  "open" function 
described above,  and a  file handle  returned in register B. The "open mode" 
parameter  is  interpreted  in the  same way  as for  the "open"  function. A 
sub-directory  will not be opened (because this is meaningless) so register B 
will be returned as 0FFh which can never be a valid file handle.














  3.49   CLOSE FILE HANDLE (45H)

     Parameters:    C = 45H (_CLOSE)
                    B = File handle
     Results:       A = Error



   This  function  releases  the  specified file  handle for  re-use. If  the 
associated file  has been written to then its directory entry will be updated 
with  a new  date and  time, the  archive attributes bit will be set, and any 
buffered data  will be  flushed to  disk. Any  subsequent attempt to use this 
file  handle will return an error. If there are any other copies of this file 
handle, created by "duplicate file handle" or "fork", then these other copies 
may still be used. 


  3.50   ENSURE FILE HANDLE (46H)

     Parameters:    C = 46H (_ENSURE)
                    B = File handle
     Results:       A = Error



   If  the file  associated with the file handle has been written to then its 
directory  entry  will  be  updated with  a new  date and  time, the  archive 
attributes bit  will be  set, and  any buffered data will be flushed to disk. 
The file handle is not released and so it can still be used for accessing the 
file, and the current file pointer setting will not be altered.




  3.51   DUPLICATE FILE HANDLE (47H)

     Parameters:    C = 47H (_DUP)
                    B = File handle
     Results:       A = Error
                    B = New file handle


   This  function creates  a copy  of the  specified file  handle. The lowest 
available  file  handle  number  will  always  be used  and a  ".NHAND" error 
returned if  there are  none available. The new file handle will refer to the 
same  file as the original and either one may be used. If the file pointer of 
one handle  is moved,  the other  one will also be moved. If either handle is 
closed the other one may still be used.







   Note that  because duplicate file handles created by this function are not 
"separately  opened", they  do not  count as  separate file  handles for  the 
purposes of  generating ".FOPEN" errors. So for example a "DUP"ed file handle 
may  be renamed  (function 53h) or have its attributes changed (function 55h) 
and the  effect will  apply to  both file handles. Note in particular that if 
one  copy of  a "DUP"ed  file handle  is deleted (function 54h) then the file 
really will be deleted and the other file handle, although still open, can no 
longer be  used safely.  If it  is used  (other than being closed, ensured or 
deleted) then an ".FDEL" error will be returned. 


  3.52   READ FROM FILE HANDLE (48H)

     Parameters:    C = 48H (_READ)
                    B = File handle
                   DE = Buffer address
		   HL = Number of bytes to read
     Results:       A = Error
                   HL = Number of bytes actually read


   The  specified number  of bytes are read from the file at the current file 
pointer position  and copied  to the buffer address specified in register DE. 
The file pointer is then updated to the next sequential byte. A ".ACCV" error 
will  be returned if the file handle was opened with the "no read" access bit 
set.


   The number of bytes read may be less than the number requested for various 
reasons, and  the number  read will be returned in register HL if there is no 
error.  In general  if less  is read  than requested  then this should not be 
treated as  an error  condition but  another read  should be done to read the 
next portion, until a ".EOF" error is returned. An ".EOF" error will never be 
returned  for a partial read, only for a read which reads zero bytes. Reading 
files in  this way  ensures that device file handles will work correctly (see 
below).


   For disk  files the number of bytes read will only be less than the number 
requested  if the  end of  the file is reached and in this case the next read 
operation will  read zero bytes and will return an ".EOF" error. When reading 
from a device file handle (for example the standard file handles 0 to 4), the 
behaviour  depends on  the particular device, and on whether it is being read 
in ASCII  or binary  mode (see  function 4Bh below). The "CON" device will be 
described  as an  example because  it is  the most  commonly used device, but 
other devices behave similarly.


   When reading from the "CON" device in binary mode, characters will be read 
from the keyboard, without any interpretation and without being echoed to the 
screen or  printer. The  exact number  of characters requested will always be 
read and there is no end of file condition. Because of the lack of any end of 
file indication, great care must be taken when reading from devices in binary 
mode.

   A  read function  call to the "CON" device in ASCII mode (the default mode 
and that  which normally  applies to  the standard  input channel), will only 
read  one line  of input.  The input line will be read from the keyboard with 
the normal  line editing  facilities available to the user, and the character 
typed  will be  echoed to the screen and to the printer if Ctrl-P is enabled. 
Special control  characters "Ctrl-P", "Ctrl-N", "Ctrl-S" and "Ctrl-C" will be 
tested  for and  will be  treated exactly  as for the console status function 
0Bh.


   When  the user types a carriage return the line will be copied to the read 
buffer, terminated  with a  CR-LF sequence  and the read function will return 
with  an appropriate  byte count.  The next  read will start another buffered 
line input  operation. If  the number of bytes requested in the read was less 
than the length of the line input then as many character as requested will be 
returned,  and the  next read  function call will return immediately with the 
next portion of the line until it has all been read.



   If the  user types a line which starts with a "Ctrl-Z" character then this 
will be interpreted as indicating end of file. The line will be discarded and 
the  read function  call will  read zero  bytes and return an ".EOF" error. A 
subsequent read after this will be back to normal and will start another line 
input. The end of file condition is thus not permanent.




  3.53   WRITE TO FILE HANDLE (49H)

     Parameters:    C = 49H (_WRITE)
                    B = File handle
                   DE = Buffer address
                   HL = Number of bytes to write
     Results:       A = Error
                   HL = Number of bytes actually written


   This function is very similar to the "read" function above (function 48h). 
The number  of bytes  specified will  be written  to the current file pointer 
position  in the file, and the file pointer will be adjusted to point to just 
after the  last byte  written. If  the file  was opened  with the  "no write" 
access bit set then a ".ACCV" error will be returned, and if the file is read 
only then a ".FILRO" error will be returned.


   If the  write goes  beyond the  current end  of file then the file will be 
extended  as necessary.  If the file pointer is already beyond the end of the 
file then  disk space  will be  allocated to  fill the  gap and  will not  be 
initialized.  If there  is insufficient disk space then a ".DKFUL" error will 
be returned  and no  data will be written, even if there was room for some of 
the data.


   The number of bytes written can usually be ignored since it will either be 
zero  if an  error is returned or it will be equal to the number requested if 
the write  was successful. It is very much more efficient to write files in a 
few  large blocks  rather than many small ones, so programs should always try 
to write in as large blocks as possible.

   This function sets a "modified" bit for the file handle which ensures that 
when the  file handle  is closed or ensured, either explicitly or implicitly, 
the  directory entry  will be  updated with the new date, time and allocation 
information. Also  the archive bit will be set to indicate that this file has 
been modified since it was last archived.


   Writing  to device  file handles is not a complicated as reading from them 
because there  are no  end of  file conditions  or line input to worry about. 
There  are some differences between ASCII and binary mode when writing to the 
"CON" device, in that a console status check is done in ASCII mode only. Also 
printer echo if enabled will only be done in ASCII mode.

 

  3.54   MOVE FILE HANDLE POINTER (4AH)

     Parameters:    C = 4AH (_SEEK) 
                    B = File handle
                    A = Method code
                DE:HL = Signed offset
     Results:       A = Error
                DE:HL = New file pointer 


   The file pointer associated with the specified file handle will be altered 
according to  the method  code and offset, and the new pointer value returned 
in DE:HL. The method code specifies where the signed offset is relative to as 
follows:

     A=0  Relative to the beginning of the file
     A=1  Relative to the current position
     A=2  Relative to the end of the file.


   Note  that an  offset of  zero with an method code of 1 will simply return 
the current  pointer value,  and with a method code of 2 will return the size 
of  the file.  No end  of file  check is  done so  it is  quite possible (and 
sometimes useful)  to set  the file  pointer beyond  the end  of the file. If 
there  are any  copies of  this file  handle created  by the  "duplicate file 
handle" function  (function 47h)  or the  "fork" function (function 60h) then 
their file pointer will also be changed. 

   The file  pointer only  has any  real meaning  on disk  files since random 
access is possible. On device files the file pointer is updated appropriately 
when  any read  or write  is done,  and can  be examined  or altered  by this 
function.  However  changing will  have no  effect and  examining it  is very 
unlikely to be useful.



  3.55   I/O CONTROL FOR DEVICES (4BH)

     Parameters:    C = 4BH (_IOCTL)
                    B = File handle
                    A = Sub-function code
                        00H => get file handle status
                        01H => set ASCII/binary mode
                        02H => test input ready
                        03H => test output ready
                        04H => find screen size
                   DE = Other parameters
     Results:       A = Error
                   DE = Other results


   This function  allows various  aspects of  file handles to be examined and 
altered.  In particular  it can  be used  to determine  whether a file handle 
refers to  a disk file or a device. This is useful for programs which want to 
behave differently for disk files and device I/O.


   This function  is passed  the file handle in register B and a sub-function 
code  in register  A which specifies one of various different operations. Any 
other  parameters  required  by  the  particular  sub-function are  passed in 
register DE and results are returned in register DE. If the sub-function code 
is invalid then a ".ISBFN" error will be returned.
 

   If A=0 then the operation is "get file handle status". This returns a word 
of flags  which give various information about the file handle. The format of 
this  word is  different for  device file  handles and disk file handles, and 
bit-7 specifies which it is. The format of the word is as follows:


For devices:    DE -     b0  set  => console input device
                         b1  set  => console output device
                     b2..b4  reserved
                         b5  set  => ASCII mode
                             clear=> binary mode
                         b6  set  => end of file
                         b7  always set (=> device)
		    b8..b15  reserved


For disk files: DE - b0..b5  drive number (0=A: etc)
                         b6  set  => end of file
                         b7  always clear (=> disk file)
		    b8..b15  reserved





   Note  that the end of file flag is the same for devices as for disk files. 
For devices  it will  be set  if the previous attempt to read from the device 
produced  a ".EOF" error and will be cleared by the next read. For disk files 
it is worked out by comparing the file pointer with the file size.

   If  A=1 then the operation is a "set ASCII/binary mode". This operation is 
only allowed  for device file handles. An ASCII/binary flag must be passed in 
bit-5  of  register  E  (exactly  where it  is returned  by "get  file handle 
status").  This is  set for  ASCII mode  and clear for binary mode. All other 
bits of register DE are ignored.


   If A=2  or 3  then the  operation is  "test input  ready" or  "test output 
ready"  respectively. In both cases a flag is returned in register E which is 
FFh if  the file  handle is  ready for  a character and 00h if not. The exact 
meaning  of "ready  for a character" depends on the device. Disk file handles 
are always  ready for  output, and are always ready for input unless the file 
pointer is at the end of file. The "CON" device checks the keyboard status to 
determine whether it is ready for input or not.



   If A=4  the the  operation is  "get screen size". This returns the logical 
screen size for the file handle with the number of rows in register D and the 
number  of columns  in register  E. For  devices with no screen size (such as 
disk  files)  both  D  and  E  will be  zero. Zero  for either  result should 
therefore be interpreted as "unlimited". For example this function is used by 
the "DIR  /W" command to decide how many files to print per line, and a value 
of zero for register E is defaulted to 80.



  3.56   TEST FILE HANDLE (4CH)

     Parameters:    C = 4CH (_HTEST)
                    B = File handle
                   DE = Drive/path/file ASCIIZ string
                                 or fileinfo block pointer
     Results:       A = Error
                    B = 00H => not the same file
                        FFH => same file


   This  rather  specialist function  is passed  a file  handle and  either a 
drive/path/file  string  or  a  fileinfo block  which identifies  a file.  It 
determines if  the two  files are  actually the  same file and returns a flag 
indicating  the result.  Note that  if the file handle is for a device rather 
than a disk file then it will always return "B=00h" to indicate "not the same 
file".


   This function allows the "COPY" command to detect certain error conditions 
such as  copying file  onto themselves  and give  the user  informative error 
messages.  It may  also be useful for other programs which need to do similar 
tests.


  3.57   DELETE FILE OR SUBDIRECTORY (4DH)

     Parameters:    C = 4DH (_DELETE)
                   DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
     Results:       A = Error


   This function  deletes the object (file or sub-directory) specified by the 
drive/path/file  string or the fileinfo block. Global filename characters are 
not  allowed  so only  one file  or sub-directory  can be  deleted with  this 
function. A  sub-directory can  only be  deleted if  it is  empty or an error 
(".DIRNE") occurs if not). The "." and ".." entries in a sub-directory cannot 
be  deleted (".DOT"  error) and neither can the root directory. A file cannot 
be deleted  if there  is a  file handle open to it (.FOPEN error) or if it is 
read only (.FILRO error).

   If  it is  a file  then any  disk space  which was allocated to it will be 
freed. If  the disk  is an MSX-DOS 2 disk then enough information is retained 
on  the disk  to allow the "UNDEL" utility program do undelete the file. This 
information is only retain ed until the next disk space allocation (usually a 
write to  a file) is done on this disk. After making this function call, if a 
fileinfo  block was passed then it must not be used again (other than passing 
it to  a "find  next entry"  function) since  the file  to which it refers no 
longer exists.


   If a device name such as "CON" is specified then no error will be returned 
but the device will not actually be deleted.




  3.58   RENAME FILE OR SUBDIRECTORY (4EH)

     Parameters:    C = 4EH (_RENAME)
                   DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
		   HL = New filename ASCIIZ string
     Results:       A = Error


   This function  renames the object (file or sub-directory) specified by the 
drive/path/file string or the fileinfo block, with the new name in the string 
pointed  to by HL. The new filename string must not contain a drive letter or 
directory path  (".IFNM" error if it does). If a device name such as "CON" is 
specified  then no error will be returned but the device will not actually be 
renamed.

   Global filename  characters are not allowed in the drive/path/file string, 
so  only one  object can be renamed by this function. However global filename 
characters are  allowed in the new filename passed in HL and where they occur 
the  existing filename  character will  be left unaltered. Checks are done to 
avoid creating an illegal filename, for example a file called "XYZ" cannot be 
renamed with  a new filename string of "????A" because the new filename would 
be "XYZ A" which is illegal. In this case a ".IFNM" error will be returned.


   If there is already an entry with the new filename then an error (".DUPF") 
is returned  to avoid  creating duplicate filenames. The "." and ".." entries 
in a sub-directory cannot be renamed (".IDOT" error) and neither can the root 
directory (it has noname). A file cannot be renamed if there is a file handle 
open to it (".FOPEN" error) although a read only file can be renamed.



   Note that  if DE pointed to a fileinfo block, this is not updated with the 
new  name of  the file.  Therefore care  must be  taken in using the fileinfo 
block after making this function call.




  3.59   MOVE FILE OR SUBDIRECTORY (4FH)

     Parameters:    C = 4FH (_MOVE)
                   DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
		   HL = New path ASCIIZ string
     Results:       A = Error


   This  function moves  the object  (file or sub-directory) specified by the 
drive/path/file string  or the  fileinfo block, to the directory specified by 
the  new path  string pointed to by HL. There must not be a drive name in the 
new path  string. If  a device  name such as "CON" is specified then no error 
will be returned but the device will not actually be moved.


   Global filename  characters are  not allowed in any of the strings so only 
one object (file or sub-directory) can be moved by this function, although if 
a sub-directory is moved, all its descendants will be moved with it. If there 
is  already an  entry of  the required  name in  the target  directory then a 
".DUPF" error  is returned  to prevent  creating duplicate filenames. The "." 
and ".." entries in a sub-directory cannot be moved (".DOT" error) and also a 
directory  cannot be  moved into  one of  its own descendants (".DIRE" error) 
since this  would create an isolated loop in the filing system. A file cannot 
be moved if there is a file handle open to it (".FOPEN" error).



   Note  that if  a fileinfo  block is  passed to this function, the internal 
information in  the fileinfo block is not updated to reflect the new location 
of the file. This is necessary because otherwise the fileinfo block could not 
be used for a subsequent "find next" function call. However it does mean that 
the fileinfo block no longer refers to the moved file and so must not be used 
for any operations on it such as "rename" or "open".



  3.60   GET/SET FILE ATTRIBUTES (50H)

     Parameters:    C = 50H (_ATTR)
                   DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
                    A = 0 => get attributes
                        1 => set attributes
                    L = New attributes byte (only if A=1)
     Results:       A = Error
                    L = Current attributes byte


   This function  is normally  used to  change the  attributes of  a file  or 
sub-directory.  It can  also be  used to  find out the current attributes but 
this is  more usually  done with  the "find  first entry"  function (function 
40h).  If A=0  then the current attributes byte for the file or sub-directory 
will just be returned in register L.


   If A=1  then the attributes byte will be set to the new value specified in 
register  L, and this new value will also be returned in register L. Only the 
system, hidden,  read only  and archive  bits may  be altered for a file, and 
only  the hidden  bit for a sub-directory. An ".IATTR" error will be returned 
if an  attempt is made to alter any other attribute bits. If a fileinfo block 
is  passed then  the attributes  byte in  it will not be updated with the new 
setting.



   Global filename  characters are  not allowed  so only  one object (file or 
sub-directory)  can have  its attributes set by this function. The attributes 
of the  root directory  cannot be  changed because  it does not have any. The 
attributes  of a  file cannot be changed if there is a file handle open to it 
(".FOPEN"  error).  The  attributes  of the  "." and  ".." directory  entries 
however can  be changed.  If a device name such as "CON" is specified then no 
error  will be  returned but  the device's  attributes will  not actually  be 
changed (since it does not have any).




  3.61   GET/SET FILE DATE AND TIME (51H)

     Parameters:    C = 51H (_FTIME)
                   DE = Drive/path/file ASCIIZ string
                                or fileinfo block pointer
                    A = 0 => get date and time
			1 => set date and time
                   IX = New time value (only if A=1)
                   HL = New date value (only if A=1)
     Results:       A = Error
                   DE = Current file time value
		   HL = Current file date value


   If  A=1 then  this function sets the date and time of last modification of 
the file or sub-directory specified by the drive/path/file string or fileinfo 
block. Global  filename characters  are not allowed in any part of the string 
so  only one  file can have its date and time modified by this function. If a 
device name such as "CON" is specified then no error will be returned but the 
device's date and time will not actually be changed.


   The date  and time  format are exactly as contained in the directory entry 
and  fileinfo blocks  (see the  "Program Interface Specification"). No checks 
are done for sensible dates or times, the values are simply stored. Note that 
if a fileinfo block is passed then the date and time stored in it will not be 
updated by this function.


   If  A=0 then  the current values are just returned. Note that although the 
time value is passed in IX, it is returned in DE. The date and time of a file 
cannot be altered (although it can be read) if there is a file handle open to 
the file (".FOPEN" error).






  3.62   DELETE FILE HANDLE (52H)

     Parameters:    C = 52H (_HDELETE)
                    B = File handle
     Results:       A = Error


   This function  deletes the  file handle associated with the specified file 
and  closes the file handle. A file handle cannot be deleted if there are any 
other separately  opened file handles open to the same file (".FOPEN" error). 
If  there are any duplicates of the file handle (created by a "duplicate file 
handle" or  "fork" function), then these duplicates will be marked as invalid 
and any attempt to use them will produce an ".HDEAD" error.



   The  error conditions  for this  function are  the same as for the "delete 
file or  sub-directory" function  (function 4Dh). The file handle will always 
be closed, even if there is an error condition such as ".FILRO" or ".FOPEN".
 








  3.63   RENAME FILE HANDLE (53H)

     Parameters:    C = 53H (_HRENAME)
                    B = File handle
		   HL = New filename ASCIIZ string
     Results:       A = Error


   This  function renames  the file associated with the specified file handle 
with the  new name  in the  string pointed to by HL. Apart from the fact that 
the  file is  specified by  a file  handle rather  than an ASCIIZ string or a 
fileinfo  block,   this  function   is  identical  to  the  "rename  file  or 
subdirectory" function (function 4Eh), and has the same error conditions.



   A file  handle cannot  be renamed if there are any other separately opened 
file  handles for  this file  (".FOPEN" error), although it can be renamed if 
there are  copies of  this file  handle, and  in this case the copies will be 
renamed.  Renaming a  file handle will not alter the file pointer but it will 
do an implicit "ensure" operation.




  3.64   MOVE FILE HANDLE (54H)

     Parameters:    C = 54H (_HMOVE)
                    B = File handle
		   HL = New path ASCIIZ string
     Results:       A = Error


   This function  moves the file associated with the specified file handle to 
the  directory specified  by the new path string pointed to by HL. Apart from 
the fact  that the  file is  specified by a file handle rather than an ASCIIZ 
string  or a  fileinfo block, this function is identical to the "move file or 
subdirectory" function (function 4Fh), and has the same error conditions.



   A file  handle cannot  be moved  if there  are any other separately opened 
file  handles for  this file  (".FOPEN" error),  although it  can be moved if 
there are  copies of  this file handle, and in this case the copies will also 
be moved. Moving a file handle will not alter the file pointer but it will do 
an implicit "ensure" operation.









  3.65   GET/SET FILE HANDLE ATTRIBUTES (55H)

     Parameters:    C = 55H (_HATTR)
                    B = File handle
                    A = 0 => get attributes
                        1 => set attributes
                    L = New attributes byte (only if A=1)
     Results:       A = Error
                    L = Current attributes byte


   This function gets or sets the attributes byte of the file associated with 
the specified  file handle. Apart from the fact that the file is specified by 
a file handle rather than an ASCIIZ string or a fileinfo block, this function 
is  identical to  the "get/set  file attributes" function (function 50h), and 
has the same error conditions.



   A  file handle  cannot have  its attributes  changed (although they can be 
read) if  there are  any other  separately opened  file handles for this file 
(".FOPEN"  error).  The  file pointer  will not  be altered  but an  implicit 
"ensure" operation will be done.




  3.66   GET/SET FILE HANDLE DATE AND TIME (56H)

     Parameters:    C = 56H (_HFTIME)
                    B = File handle
                    A = 0 => get date and time
			1 => set date and time
                   IX = New time value (only if A=1)
                   HL = New date value (only if A=1)
     Results:       A = Error
                   DE = Current file time value
		   HL = Current file date value


   This  function gets  or sets the date and time of the file associated with 
the specified  file handle. Apart from the fact that the file is specified by 
a file handle rather than an ASCIIZ string or a fileinfo block, this function 
is identical to the "get/set file date and time" function (function 51h), and 
has the same error conditions.


   A  file handle cannot have its date and time changed (although they can be 
read) if  there are  any other  separately opened  file handles for this file 
(".FOPEN"  error).  The  file pointer  will not  be altered  but an  implicit 
"ensure" operation will be done.




  3.67   GET DISK TRANSFER ADDRESS (57H)

     Parameters:    C = 57H (_GETDTA)
     Results:      DE = Current disk transfer address



   This  function returns  the current disk transfer address. This address is 
only used  for the  "traditional" CP/M  style FCB  functions and the absolute 
sector read and write functions.
 



  3.68   GET VERIFY FLAG SETTING (58H)

     Parameters:    C = 58H (_GETVFY)
     Results:       B = 00H => verify disabled
                        FFH => verify enabled



   This  function simply  returns the  current state of the verify flag which 
can be set with MSX-DOS function 2Eh.




  3.69   GET CURRENT DIRECTORY (59H)

     Parameters:    C = 59H (_GETCD)
                    B = Drive number (0=current, 1=A: etc)
		   DE = Pointer to 64 byte buffer
     Results:       A = Error
                   DE = Filled in with current path



   This  function  simply  gets  an  ASCIIZ  string representing  the current 
directory of the specified drive into the buffer pointed to by DE. The string 
will not  include a drive name or a leading or trailing "\" character, so the 
root directory is represented by a null string. The drive will be accessed to 
make sure that the current directory actually exists on the current disk, and 
if  not then  the current  directory will  be set back to the root and a null 
string returned.










  3.70   CHANGE CURRENT DIRECTORY (5AH)

     Parameters:    C = 5AH (_CHDIR)
                   DE = Drive/path/file ASCIIZ string
     Results:       A = Error



   The drive/path/file  string must  specify a  directory rather than a file. 
The  current directory  of the drive will be changed to be this directory. If 
the  specified  directory does  not exist  then the  current setting  will be 
unaltered and a ".NODIR" error returned.




  3.71   PARSE PATHNAME (5BH)

     Parameters:    C = 5BH (_PARSE)
                    B = Volume name flag (bit 4)
                        DE = ASCIIZ string for parsing
     Results:       A = Error
                   DE = Pointer to termination character
                   HL = Pointer to start of last item
                    B = Parse flags
                    C = Logical drive number (1=A: etc)


   This function is purely a string manipulation function, it will not access 
the disks  at all  and it  will not  modify the  user's string  at all. It is 
intended to help transient programs in parsing command lines.


   The volume  name flag (bit 4 of register B; it is in the same bit position 
as  the volume  name bit in an attributes byte) determines whether the string 
will be  parsed as  a "drive/path/file"  string (if  the bit is cleared) or a 
"drive/volume" string (if the bit is set).


   The pointer  returned in DE will point to the first character which is not 
valid in a pathname string, and may be the null at the end of the string. See 
the "Command Specification" for details of the syntax of pathname strings and 
also for a list of valid characters.


   The  pointer returned  in HL will point to the first character of the last 
item of  a string  (filename portion). For example, when a string "A:\XYZ\P.Q 
/F" was passed, DE will point to the white space character before "/F" and HL 
will  point to "P". If the parsed string ends with a character "\" or is null 
(apart from  drive name),  then there  will be no "last item", thus HL and DE 
will  point to the same character. In this case, some special procedures will 
be needed to all the programs which use this function.



   The  drive number returned in register C is the logical drive specified in 
the string.  If the  string did not start with a drive letter then register C 
will  contain the  default drive  number, since  the default  drive has  been 
implicitly specified. Register C will never be zero.


   The  parse flags  returned in  register B  indicate various  useful things 
about the  string. For  a volume  name bits  1, 4,  5, 6 and 7 will always be 
clear. For a filename, bits 3 to 7 relate to the last item on the string (the 
"filename" component). The bit assignments are as follows: 

b0 - set if any characters parsed other than drive name
b1 - set if any directory path specified
b2 - set if drive name specified
b3 - set if main filename specified in last item
b4 - set if filename extension specified in last item
b5 - set if last item is ambiguous
b6 - set if last item is "." or ".."
b7 - set if last item is ".."




  3.72   PARSE FILENAME (5CH)

     Parameters:    C = 5CH (_PFILE)
                   DE = ASCIIZ string for parsing
                   HL = Pointer to 11 byte buffer
     Results:       A = Error (always zero)
                   DE = Pointer to termination character
                   HL = Preserved, buffer filled in
                    B = Parse flags


   This function is purely a string manipulation function, it will not access 
disks at  all and will not modify the string at all. It is intended mainly to 
help  transient programs  in printing  out filenames  in a formatted way. The 
ASCIIZ string will be parsed as a single filename item, and the filename will 
be  stored  in the  user's 11  byte buffer  in expanded  form, with  both the 
filename and the extension padded out with spaces.


   The parse  flags returned  in register  B are  identical to  those for the 
"parse  pathname" function  above (function 5Bh), except that bits 0, 1 and 2 
will always  be clear.  The user's  buffer will  always be filled in, even if 
there  is no  valid filename  in the string, in which case the buffer will be 
filled with spaces. "*" characters will be expanded to the appropriate number 
of "?"s.  If either  the filename  or the filename extension is too long then 
the excess characters will be ignored.


   The pointer  returned in  register DE will point to the first character in 
the  string which  was not part of the filename, which may be the null at the 
end of  the string.  This character  will never be a valid filename character 
(see the "Command Specification" for details of valid filename characters).




  3.73   CHECK CHARACTER (5DH)

     Parameters:    C = 5DH (_CHKCHR)
                    D = Character flags
                    E = Character to be checked
     Results:       A = 0 (never returns an error)
                    D = Updated character flags
                    E = Checked (upper cased) character


   This  function allow  language independent  upper casing of characters and 
also helps with handling 16-bit characters and manipulation of filenames. The 
bit assignments in the character flags are as follows:

   b0   - set to suppress upper casing
   b1   - set if first byte of 16-bit character
   b2   - set if second byte of 16-bit character
   b3   - set => volume name (rather than filename)
   b4   - set => not a valid file/volume name character
b5...b7 - reserved (always clear)


   Bit 0  is used  to control upper casing. If it is clear then the character 
will be upper cased according to the language setting of the machine. If this 
bit  is  set  then the  returned character  will always  be the  same as  the 
character passed.


   The two  16-bit character  flags (bits 1 and 2) can both be clear when the 
first  character of  a string  is checked  and the  settings returned  can be 
passed straight  back to  this function  for each  subsequent character. Care 
must  be taken  with these  flags when moving backwards through strings which 
may contain 16-bit characters.



   Bit  4 is  set on return if the character is one of the set of filename or 
volume name  terminator characters. Bit 3 is simply used to determine whether 
to  test for filename or volume name characters since the sets are different. 
16-bit characters  (either byte)  are never  considered as volume or filename 
terminators.










  3.74   GET WHOLE PATH STRING (5EH)

     Parameters:    C = 5EH (_WPATH)
			DE = Pointer to 64 byte buffer
     Results:       A = Error
                   DE = Filled in with whole path string
		   HL = Pointer to start of last item


   This  function simply copies an ASCIIZ path string from an internal buffer 
into the  user's buffer.  The string  represents the whole path and filename, 
from  the root  directory, of  a file  or sub-directory located by a previous 
"find first entry" or "find new entry" function. The returned string will not 
include a  drive, or  an initial "\" character. Register HL will point at the 
first  character of  the last  item on  the string, exactly as for the "parse 
path" function (function 5Bh).


   If a  "find first entry" or "find new entry" function call is done with DE 
pointing to an ASCIIZ string then a subsequent "get whole path" function call 
will  return a string representing the sub-directory or file corresponding to 
the  fileinfo   block  returned   by  the  "find"  function.  If  this  is  a 
sub-directory  then the  fileinfo block  may be passed back in register DE to 
another "find  first entry"  function call,  which will  locate a file within 
this  sub-directory. In  this case  the newly located file will be added onto 
the already  existing whole  path string internally, and so a subsequent "get 
whole  path string" function call will return a correct whole path string for 
the located file.



   Great care must be taken in using this function because the internal whole 
path  string is modified by many of the function calls, and in many cases can 
be invalid.  The "get  whole path"  function call  should be done immediately 
after  the  "find  first  entry"  or "find  new entry"  function to  which it 
relates.




  3.75   FLUSH DISK BUFFERS (5FH)

     Parameters:    C = 5FH (_FLUSH)
                    B = Drive number (0=current, FFH=all)
                    D = 00H => Flush only
		      = FFH => Flush and invalidate
     Results:       A = Error


   This  function flushes  any dirty disk buffers for the specified drive, or 
for all drives if B=FFh. If register D is FFh then all buffers for that drive 
will also be invalidated. 




  3.76   FORK TO CHILD PROCESS (60H)

     Parameters:    C = 60H (_FORK)
     Results:       A = Error
                    B = Process id of parent process


   This function  informs the  system that  a child  process is  about to  be 
started.  Typically this  is a new program or sub-command being executed. For 
example COMMAND2.COM does a "fork" function call before executing any command 
or transient program.


A new set of file handles is created, and any current file handles which were 
opened with the "inheritable" access mode bit set (see the "open file handle" 
function -  function 43h),  are copied  into the new set of file handles. Any 
file handles which were  opened with  the "inheritable" bit clear will not be copied and so will 
not be  available to the child process. The standard file handles (00h...05h) 
are inheritable and so these will be copied.


   A new process id is allocated for the child process and the process id. of 
the parent  process is  returned so  that a  later "join"  function call  can 
switch  back to  the parent process. A ".NORAM" error can be produced by this 
function if there is insufficient memory to duplicate the file handles.



   Because  the child  process now  has a  copy of  the previous file handles 
rather than  the originals,  if one  of them is closed then the original will 
remain  open. So  for example if the child process closes the standard output 
file handle  (file handle number 1) an re-opens it to a new file, then when a 
"join" function is done to return to the parent process the original standard 
output channel will still be there.




  3.77   REJOIN PARENT PROCESS (61H)

     Parameters:    C = 61H (_JOIN)
                    B = Process id of parent, or zero
     Results:       A = Error
                    B = Primary error code from child
                    C = Secondary error code from child


   This function  switches back  to the  specified parent process and returns 
the  error code  which the child process terminated with in register B, and a 
secondary error  code from the child in register C. Although the relationship 
between  parent and  childprocesses is strictly one-to-one, this function can 
jump back several levels by giving it a suitable process id. A ".IPROC" error 
will be returned if the process id is invalid.


   The child  process's set  of file handles are automatically closed and the 
parent  process's set of file handles becomes active again. Also any user RAM 
segments which the child process had allocated will be freed.


   If the  process id  passed to  this function is zero then a partial system 
re-initialisatin  is done. All file handles are closed and the standard input 
and output handles re-opened and all user segments are freed. This should not 
normally be  done by  a user  program if  it intends to return to the command 
interpreter  since the  command interpreter will not be in a consistent state 
after this.


   This function takes great care that the freeing of memory and adjusting of 
process id  is done  before actually closing any file handles and thus before 
accessing  the disk. This ensures that if a disk error occurs and is aborted, 
the join  operation will  have been  done successfully. However if a "join 0" 
produces a disk error which is aborted, then the re-initialization of default 
file  handles will not have been done. In this case another "join 0" function 
call should  be done  and this  will not attempt access disk (because all the 
files have been closed) and so will be successful.



   Note that  if this function call is made via 0F37Dh then registers B and C 
will  not return  the error  codes. This  is because  program termination and 
abort handling  must be  done by the application program. The error code will 
have  been passed  to the abort vector and code there must remember the error 
code if  it needs  to. See the "terminate with error code" function (function 
62h) for the meaning of the primary and secondary error code. 
























  3.78   TERMINATE WITH ERROR CODE (62H)

     Parameters:    C = 62H (_TERM)
                    B = Error code for termination
     Results:       Does not return


   This  function terminates the program with the specified error code, which 
may be  zero indicating no error. This function call will never return to the 
caller  (unless a  user abort  routine executes  forces it  to - see function 
63h). The operation of this function is different depending on whether it was 
called  from  the  MSX-DOS  environment  via  00005h or  from the  disk BASIC 
environment via 0F37Dh.


   If called  via 00005h  then if  a user  abort routine  has been defined by 
function  63h it  will be  called with  the specified  error code (and a zero 
secondary error code). Assuming that this routine returns, or if there was no 
user abort  routine defined,  then control  will be  passed back  to whatever 
loaded  the transient program via a jump at location 00000h. This will almost 
always  be  the command  interpreter, but  in some  cases it  may be  another 
transient program.  The error  code will  be remembered by the system and the 
next  "join" function  (function 61h)  which is  done will  return this error 
code. The command interpreter will print an error message for any code in the 
range 20h...FFh, but will not print a message for errors below this.



   If this function is called from the disk BASIC environment via 0F37Dh then 
control  will be  passed to the abort vector at location "BREAKVECT". In this 
environment there  is no  separately defined user abort routine and the error 
code  must be  remembered by  the code at "BREAKVECT" because "join" will not 
return the error code.






















  3.79   DEFINE ABORT EXIT ROUTINE (63H)

     Parameters:    C = 63H (_DEFAB)
		   DE = Address of abort exit routine
			0000H to un-define routine
     Results:       A = 0 (never generates errors)


   This function  is only  available when  called via  location 00005h in the 
MSX-DOS  environment. It  cannot be  called at  location 0F37Dh from the disk 
BASIC environment.

   If  register DE  is zero  then a  previously defined abort routine will be 
undefined, otherwise  a new  one will  be defined.  The abort routine will be 
called by the system whenever the transient program is about to terminate for 
any  reason other  than a direct jump to location 0000h. Programs written for 
MSX-DOS  2  should  exit  with a  "terminate with  error code"  function call 
(function 061h) rather than a jump to location 0000h.


   The user  abort routine  will be  entered with the user stack active, with 
IX,  IY and  the alternate  register set as it was when the function call was 
made and  with the  whole TPA  paged in.  The termination  error code will be 
passed to the routine in register A with a secondary error code in register B 
and  if the  routine executes a "RET" then the values returned in registers A 
and  B  will  be  stored as  the error  codes to  be returned  by the  "join" 
function, and  normally printed out by the command interpreter. Alternatively 
the  routine may jump to some warm start code in the transient program rather 
than returning. The system will be in a perfectly stable state able to accept 
any function calls.


   The primary  error code  passed to  the routine  in register A will be the 
code  which the  program itself  passed to  the "terminate  with error  code" 
function (which  may be  zero) if this is the reason for the termination. The 
routine will also be called if a Ctrl-C or Ctrl-STOP is detected (".CTRLC" or 
".STOP"  error), if  a disk error is aborted (".ABORT" error), or if an error 
occurred  on  one of  the standard  input or  output channels  being accessed 
through MSX-DOS function calls 01h...0Bh (".INERR" or ".OUTERR").


   The errors ".ABORT", ".INERR" and ".OUTERR" are generated by the system as 
a  result of  some other  error. For  example a  ".ABORT" can  result from  a 
".NRDY" error,  or a  ".INERR" can result from a ".EOF" error. In these cases 
the original error code (".NRDY" or ".EOF") is passed to the abort routine in 
register  B as  the secondary  error code.  For all  other errors there is no 
secondary error code and register B will be zero.


   If the abort routine executes "POP HL : RET" (or equivalent) rather than a 
simple  return,  then  control  will  pass  to  the  instruction  immediately 
following the MSX-DOS call or BIOS call in which the error occurred. This may 
be useful in conjunction with a disk error handler routine (see function 64h) 
to  allow  an option  to abort  the current  MSX-DOS call  when a  disk error 
occurs.




  3.80   DEFINE DISK ERROR HANDLER ROUTINE (64H)

     Parameters:    C = 64H (_DEFER)
                   DE = Address of disk error routine
			0000H to un-define routine
     Results:       A = 0 (never generates errors)


   This function specifies the address of a user routine which will be called 
if a  disk error  occurs. The routine will be entered with the full TPA paged 
in, but with the system stack in page-3 active and none of the registers will 
be preserved from when the MSX-DOS function call was made.


   The error routine can make MSX-DOS calls but must be very careful to avoid 
recursion. The list of function calls in section 2 of this document indicates 
which function  calls can  be safely  made from  a user  error routine.  This 
routine  is called  with the redirection status being temporarily invalidated 
in case  the standard  I/O channels  have been  redirected. See  the "get/set 
redirection state" function (function 70h) for details of this.


   The  specification of  parameters and results for the routine itself is as 
below. All  registers including  IX, IY and the alternate register set may be 
destroyed but the paging and stack must be preserved. The routine must return 
to the system, it must not jump away to continue the transient program. If it 
wants to do this then it should return A=1 ("abort") and a user abort routine 
will then get control and this may do whatever it wants to.



     Parameters:    A = Error code which caused error
		    B = Physical drive
                    C = b0 - set if writing
                        b1 - set if ignore not recommended
                        b2 - set if auto-abort suggested
			b3 - set if sector number is valid
                   DE = Sector number (if b3 of C is set)
     Results:       A = 0 => Call system error routine
                        1 => Abort
                        2 => Retry
                        3 => Ignore









  3.81   GET PREVIOUS ERROR CODE (65H)

     Parameters:    C = 65H (_ERROR)
     Results:       A = 0
                    B = Error code from previous function



   This  function allows  a user  program to  find out  the error  code which 
caused the  previous MSX-DOS  function call  to fail.  It is intended for use 
with the old CP/M compatible functions which do not return an error code. For 
example  if a  "create file  FCB" function  returns A=0FFh thee could be many 
reasons  for  the  failure  and  doing  this  function  call will  return the 
appropriate on, for example ".DRFUL" or ".SYSX".




  3.82   EXPLAIN ERROR CODE (66H)

     Parameters:    C = 66H (_EXPLAIN)
                    B = Error code to be explained
                   DE = Pointer to 64 byte string buffer
     Results:       A = 0
                    B = 0 or unchanged
		   DE = Filled in with error message


   This  function allows  a user  program to get an ASCIIZ explanation string 
for a  particular error  code returned by any of the MSX-DOS functions. If an 
error comes from one of the old functions then "get previous error code" must 
be  called first  to get  the real  error code  and then this function can be 
called to get an explanation string.


   The "Program Interface Specification" contains a list of all the currently 
defined  error codes  and the messages for them. Foreign language versions of 
the system  will of  course have  different messages.  If the error code does 
have  a built  in explanation  string then  this string  will be returned and 
register B  will be  set to  zero. If  there is  no explanation string then a 
string  of the  form: "System error 194" or "User error 45" will be returned, 
and register  B will  be unchanged.  (System errors  are those  in the  range 
40h...FFh and user errors are 00h...3Fh.) 












  3.83   FORMAT A DISK (67H)

     Parameters:    C = 67H (_FORMAT)
                    B = Drive number (0=>current, 1=>A:)
                    A =    00H    => return choice string
                        01H...09H => format this choice
                        0AH...FDH => illegal
			FEH, FFH  => new boot sector
                   HL = Pointer to buffer (if A=1...9)
		   DE = Size of buffer (if A=1...9)
     Results:       A = Error
                    B = Slot of choice string (only if A=0 on entry)
                   HL = Address of choice string (only if A=0 on entry)


This function  is used  to format  disks and  is really only provided for the 
"FORMAT"  command although other programs may use it (with care) if they find 
it useful.  It has  three different  options which  are selected  by the code 
passed in register A.


   If  A=0  then  registers  B  and  HL  return the  slot number  and address 
respectively  of an ASCIIZ string which specifies the choice of formats which 
is  available.  A ".IFORM"  error will  be returned  if this  disk cannot  be 
formatted (for  example the RAM disk). Normally the string will be read using 
the  "RDSLT" routine  and displayed  on the screen followed by a "? " prompt. 
The user  then specifies a choice "1"..."9" and this choice is passed back to 
the  "format" function,  after a  suitable warning prompt, to actually format 
the disk. If A=0, in some cases zero is returned in HL. This means that there 
is only  one kind of the format and no prompt is required. There is no way of 
knowing  what  disk  format  a  particular  choice  refers to  since this  is 
dependant on the particular disk driver.


   If A=01h...09h then this is interpreted as a format choice and a disk will 
be formatted  in the  specified drive  with no further prompting. Register HL 
and  DE must specify a buffer area to be used by the disk driver. There is no 
way of  knowing how big this buffer should be so it is best to make it as big 
as  possible. If  the buffer  crosses page boundaries then this function will 
select the largest portion of it which is in one page for passing to the disk 
driver. Many disk drivers do not use this buffer at all.



   If  A=FFh then  the disk  will not  actually be  formatted, but it will be 
given a  new boot  sector to  make the  disk a  true MSX-DOS  2 disk. This is 
designed  to update  old MSX-DOS 1.0 disks to have a volume id and thus allow 
the full  disk checking and undeletion which MSX-DOS 2 allows. The case A=FEh 
is  the  same  as  A=FFh  except that  only the  disk parameters  are updated 
correctly  and the  volume id does not overwrite the boot program. Also there 
are some  MSX-DOS 1.0  implementations which  put an incorrect boot sector on 
the  disk and  these disks  cannot be  used by MSX-DOS 2 until they have been 
corrected by this function.


   The  "new  boot  sector"  function  is mainly  intended for  the "FIXDISK" 
utility program, but may be used by other programs if they find it useful. If 
it  is used  then a  "get format  choice" function  call (A=0) should be done 
first and  if this  returns an  error (typically ".IFORM") then the operation 
should be aborted because this is a drive which does not like to be formatted 
and the disk could be damaged by this function.
 


  3.84   CREATE OR DESTROY RAMDISK (68H)

     Parameters:    C = 68H (_RAMD)
                    B =     00H => destroy RAM disk
                        1...FEH => create new RAM disk
                            FFH => return RAM disk size
     Results:       A = Error
                    B = RAM disk size


   If  register B=0FFh  then this  routine just returns the number of 16k RAM 
segments which  are allocated  to the  RAM disk  currently. A  value of  zero 
indicates  that  there  is no  RAM disk  currently defined.  If B=0  then the 
current  RAM disk  will be destroyed, loosing all data which it contained and 
no error will be returned if there was no RAM disk.


   Otherwise, if  B is in the range 01h...FEh then this function will attempt 
to  create a  new RAM  disk using  the number  of 16k  segments specified  in 
register  B.  An  error  will  be  returned if  there is  already a  RAM disk 
(".RAMDX") or  if there is not even one segment free (".NORAM"). If there are 
insufficient  free RAM segments to make a RAM disk of the specified size then 
the largest one possible will be created. No error is returned in this case.
 


   In  all cases the size of the RAM disk will be returned in register B as a 
number of segments. Note that some of the RAM is used for the file allocation 
tables and  the root  directory so  the size  of the RAM disk as indicated by 
"DIR" or "CHKDSK" will be somewhat smaller than the total amount of RAM used. 
The  RAM will  always be  assigned the  drive letter  "H:" regardless  of the 
number of drives in the system.














  3.85   ALLOCATE SECTOR BUFFERS (69H)

     Parameters:    C = 69H (_BUFFER)
                    B = 0 => return number of buffers
                        else number of buffers required
     Results:       A = Error
		    B = Current number of buffers


   If  B=0 then this function just returns the number of sector buffers which 
are currently  allocated. If B<>0 then this function will attempt to use this 
number  of sector  buffers (must always be at least 2). If it cannot allocate 
as many as requested then it will allocate as many as possible and return the 
number in  register B  but will  not return  an error.  The number  of sector 
buffers can be reduced as well as increased.



   The  sector buffers  are allocated in a 16k RAM segment outside the normal 
64k so  the number  of buffers  does not  detract from  the size  of the TPA. 
However  the number of buffers does affect efficiency since with more buffers 
allow more  FAT and directory sectors to be kept resident. The maximum number 
of buffers will be about 20.




  3.86   LOGICAL DRIVE ASSIGNMENT (6AH)

     Parameters:    C = 6AH (_ASSIGN)
		    B = Logical drive number (1=A: etc)
                    D = Physical drive number (1=A: etc)
     Results:       A = Error
                    D = Physical drive number (1=A: etc)


   This  function controls the logical to physical drive assignment facility. 
It is  primarily intended for the "ASSIGN" command although user programs may 
want to use it to translate logical drive numbers to physical drive numbers.


   If both  B and  D are  non-zero then  a new  assignment will be set up. If 
register  B is  non-zero and  register D  is zero then any assignment for the 
logical drive  specified by B will be cancelled. If both register B and D are 
zero  then all  assignments will  be cancelled. If register B is non-zero and 
register D is FFh then the current assignment for the logical drive specified 
by register B will simply be returned in register D.


   All  drives used  in the  various function calls, including drive names in 
strings  and  drive  numbers  as parameters  to function  calls, are  logical 
drives. However  the drive number passed to disk error routines is a physical 
drive  so  if  "ASSIGN"  has  been  used  these  may  be  different  from the 
corresponding logical drive.





  3.87   GET ENVIRONMENT ITEM (6BH)

     Parameters:    C = 6BH (_GENV)
                   HL = ASCIIZ name string
                   DE = Pointer to buffer for value
                    B = Size of buffer
     Results:       A = Error
                   DE = Preserved, buffer filled in if A=0



   This function gets the current value of the environment item whose name is 
passed  in register  HL. A  ".IENV" error  is returned  if the name string is 
invalid. If there is no environment item of that name then a null string will 
be returned  in the  buffer. If  there is an item of that name then its value 
string  will be  copied to  the buffer.  If the  buffer is too small then the 
value string  will be truncated with no terminating null and a ".ELONG" error 
will  be returned. A buffer 255 bytes will always be large enough since value 
strings cannot be longer than this (including the terminating null).
 



  3.88   SET ENVIRONMENT ITEM (6CH)

     Parameters:    C = 6CH (_SENV)
                   HL = ASCIIZ name string
                   DE = ASCIIZ value string
     Results:       A = Error



   This  function sets  a new environment item. If the name string is invalid 
then a ".IENV" error is returned, otherwise the value string is checked and a 
".ELONG" error  returned if  it is  longer than 255 characters, or a ".NORAM" 
error  if there  is insufficient memory to store the new item. If all is well 
then any  old item  of this  name is deleted and the new item is added to the 
beginning  of the  environment list.  If the  value string  is null  then the 
environment item will be removed.












  3.89   FIND ENVIRONMENT ITEM (6DH)

     Parameters:    C = 6DH (_FENV)
                   DE = Environment item number
                   HL = Pointer to buffer for name string
     Results:       A = Error
                   HL = Preserved, buffer filled in



   This  function is  used to  find out  what environment items are currently 
set. The  item number  in register DE identifies which item in the list is to 
be  found (the  first item  corresponds to  DE=1). If there is an item number 
<DE> then the name string of this item will be copied into the buffer pointed 
to by  HL. If the buffer is too small then the name will be truncated with no 
terminating null, and a ".ELONG" error returned. A 255 byte buffer will never 
be  too small.  If there  is no  item number  <DE> then a null string will be 
returned, since an item can never have a null name string.





  3.90   GET/SET DISK CHECK STATUS (6EH)

     Parameters:    C = 6EH (_DSKCHK)
                    A = 00H => get disk check status
                        01H => set disk check status
                    B = 00H => enable (only if A=01H)
                        FFH => disable (only if A=01H)
     Results:       A = Error
                    B = Current disk check setting


   If A=0  then the  current value  of the disk check variable is returned in 
register  B. If  A=01h then the variable is set to the value in register B. A 
value of 00h means that disk checking is enabled and a non-zero means that it 
is disabled. The default state is enabled.



   The disk check variable controls whether the system will re-check the boot 
sector of  a disk  to see  whether it  has changed,  each time a file handle, 
fileinfo  block  or  FCB  is  accessed.  If  it is  enabled then  it will  be 
impossible  to accidentally  access the  wrong disk by changing a disk in the 
middle of  an operation,  otherwise this will be possible and may result in a 
corrupted  disk. Depending  on the  type of disk interface, there may be some 
additional overhead  in having  this feature enabled although with many types 
of  disk (those with explicit disk change detection hardware) it will make no 
difference and the additional security is well worth having.





  3.91   GET MSX-DOS VERSION NUMBER (6FH)

     Parameters:    C = 6FH (_DOSVER)
     Results:       A = Error (always zero)
                   BC = MSX-DOS kernel version
                        DE = MSXDOS2.SYS version number


   This function allows a program to determine which version of MSX-DOS it is 
running  under. Two  version numbers  are returned, one in BC for the MSX-DOS 
kernel in  ROM and  the other  is DE for the MSXDOS2.SYS system file. Both of 
these  version numbers  are BCD  values with  the major version number in the 
high byte  and the  two digit  version number in the low byte. For example if 
there were a version 2.34 of the system, it would be represented as 0234h.



   For compatibility  with MSX-DOS 1.0, the following procedure should always 
be followed in using this function. Firstly if there is any error (A<>0) then 
it  is not  MSX-DOS at  all. Next  look at register B. If this is less than 2 
then the system is earlier than 2.00 and registers C and DE are undefined. If 
register B  is 2 or greater then registers BC and DE can be used as described 
above.  In general  the version  number which  should be  checked (after this 
procedure) is the MSXDOS2.SYS version in register DE.































  3.92   GET/SET REDIRECTION STATE (70H)

     Parameters:    C = 70H (_REDIR)
                    A = 00H => get redirection state
                        01H => set redirection state
                    B = New state.   b0 - standard input
                                     b1 - standard output
     Results:       A = Error
                    B = Redirection state before command
                         b0 set => input is redirected
                         b1 set => output is redirected


   This  function is  provided primarily  for disk  error routines  and other 
character  I/O  which  must  always  go  to  the  console  regardless  of any 
redirection.  When  the CP/M  character functions  (functions 01h...0Bh)  are 
used, they  normally refer  to the  console. However if the standard input or 
output file handles (file handles 0 and 1) have been closed and reopened to a 
disk  file, then  the CP/M character functions will also go to the disk file. 
However certain output such as disk error output must always go to the screen 
regardless.


   This  function allows  any such redirection to be temporarily cancelled by 
calling this  function with A=1 and B=0. This will ensure that any subsequent 
CP/M  console I/O  will go  to the console, and will also return the previous 
setting so  that this  can be  restored afterwards.  The system is a somewhat 
unstable  state when  the redirection  state has  been altered  like this and 
there are  many function  calls which  will reset the redirection to its real 
state   over-riding  this  function.  In  general  any  function  call  which 
manipulates file  handles, such  as "open",  "close", "duplicate"  and so on, 
will  reset the  redirection state.  The effect of this function is therefore 
purely temporary.








                ++++++++++  END OF DOCUMENT  ++++++++++
                                                                                                       