MILC logo

IndexVorigeVolgendeLeeg

Function calls
ASCII, 01-09-94


    
3.   MSX-DOS FUNCTION CALLS
===========================

3.1   CALLING CONVENTIONS

     MSX-DOS function calls are made by putting the function code in register 
C  with any  other parameters  required in  the other main registers and then 
executing a  "CALL 5"  instruction. The  operation will  be performed and the 
results will be returned in various registers depending on the function.

     Generally  all the  main registers (AF, BC, DE and HL) will be corrupted 
by MSX-DOS  calls or  will return  results. The  alternate register set (AF', 
BC',  DE' and  HL') are  always preserved, whilst the index registers (IX and 
IY) are preserved except in the one or two cases where they return results.

     Only  a  small  amount of  space (8  bytes) is  needed on  the transient 
program's  stack because  MSX-DOS switches  to an  internal stack  when it is 
called.

     For compatibility  all functions  which have  a CP/M  counterpart return 
with  A=L and  B=H. Frequently  A returns an error flag, with zero indicating 
success and 01h or FFh indicating failure.

     All of  the new  MSX-DOS functions (function code above 40h) return with 
an  error code  in A  and any  other results  in the other main registers. An 
error code  of 0  means no  error, whilst  any non-zero  code means  an error 
occurred,  the exact  nature of which can be found by looking at the value. A 
list of error codes and messages is given in section 6. An "explain" function 
is provided  which will  give an  ASCII explanation  string for an error code 
(see Function Specification for details).

     The  actual functions  available are  documented in the MSX-DOS Function 
Specification.

3.2   DEVICES AND CHARACTER I/O

     Wherever  a filename  is given to an MSX-DOS function, a device name may 
also be  given. These  devices are  used for  character based I/O and allow a 
program  to access  a disk file or a character device in exactly the same way 
without having to know which it is using.

     The syntax of device names is identical to that of filenames so programs 
do  not need  any special  handling to use device names. This applies both to 
the  new  MSX-DOS  2  functions and  the CP/M  compatible FCB  functions. The 
reserved filenames used for devices are:

     CON  - screen output, keyboard input
     PRN  - printer output
     LST  - printer output
     AUX  - auxiliary output/input
     NUL  - null device

     When  any of  these appear  as the  main part of a filename, it actually
refers to  the device; the extension is ignored. Most function calls that use 
files  can  also  use  devices.  For  example,  a  filename  of  CON  can  be 
successfully  given  to  the  "rename  file"  function  or the  "delete file" 
function. No error will be returned but the device will be unaffected.

     The  AUX device  mentioned above  does not do anything by default, but a 
routine may  be hooked  into it  so that  it refers  for example  to a serial 
driver.  The NUL  device does not actually do anything; output characters are 
ignored and  an end-of-file  is always  input. The  LST and  PRN devices  are 
identical.

     The CON device is used to read from the keyboard or write to the screen. 
When reading  from the  CON device,  the system  will read  a line  at a time 
allowing  the user to use line editing facilities. Only when the user types a 
CR (carriage return) will the line be entered. End of input is signified by a 
Ctrl-Z character at the start of a line.

     The system  automatically opens  several file  handles to these standard 
devices  (see section  3.3 for  details). These  file handles  may be used by 
programs foraccessing  the standard  devices. Alternatively  a program can do 
character  I/O by  using the  traditional CP/M character functions (functions 
01h...0Bh).  These  two  methods  are  both  acceptable but  they should  not 
normally be mixed since they use separate buffering schemes and so characters 
can get lost in these buffers.

     The  redirection is specified at the command line, both of these methods 
(standard file  handles and  character functions) will be redirected. However 
it  is preferable  to use  the standard file handles and to read and write in 
large blocks because when accessing disk files these will be very much faster 
than using the character functions.

     Even  if the redirection was specified at the command line, programs may 
sometimes need  to do  screen output and keyboard input which will bypass any 
redirection. For example disk error handling routines may need to do this. To 
facilitate this, there is a function provided which allows redirection of the 
character  functions to  be temporarily  cancelled. This  is described in the 
"Function Specification" document (function number 70h).

3.3   FILE HANDLES

     File handles  are the method by which files are read from and written to 
using  the new MSX-DOS functions. File handles may also be used to manipulate 
files in other ways (e.g. the manipulation of the file attributes).

     A file  handle is an 8 bit number which refers to a particular open file 
or  device.  A  new  file  handle is  allocated when  the "open  file handle" 
(function  43H) or  "create file handle" (function 44H) function is used. The 
file handle  can be  used to  read and  write data to the file and remains in 
existence  until  the  "close  file  handle" (function  45H) or  "delete file 
handle"  (function 52H)  function is  called. Other operations can be done on 
files using  file handles,  such as  changing the  attributes or renaming the 
files to which they refer.


     Whenever MSX-DOS  allocates a  new file  handle, it  will use the lowest 
number  available. The  maximum file  handle number in the current version is 
63. In  future versions  this may be increased but will never be greater than 
127, so file handles can never be negative.

     Space  for  the  internal  data  structures  used  for  file  handles is 
allocated  dynamically within a 16K RAM segment (the "data segment") so there 
is no  fixed limit  to the  number of  file handles  which can be open at one 
time. This segment is kept outside the TPA, so anything stored there does not 
reduce  TPA size.  As well  as keeping  internal file handle information, the 
system also keeps disk buffers and environment strings in the data segment.

     Various  file  handles  are  pre-defined  and  are already  open when  a 
transient program is executed. These file handles refer to the standard input 
and output  devices (see  section 3.2).  The "traditional" CP/M style MSX-DOS 
character I/O functions actually refer to these file handles.

     A  transient program  actually gets  a copy  of the  standard input  and 
output file  handles which the command interpreter was using, rather than the 
originals.  This means  that the  program can freely close these file handles 
and re-open  them to  different destinations  and need  not reset them before 
terminating.

     The default file handles and their destinations are:

          0 - Standard input (CON)
          1 - Standard output (CON)
          2 - Standard error input/output (CON)
          3 - Standard auxiliary input/output (AUX)
          4 - Standard printer output (PRN)

     When the  command interpreter is about to execute a command (for example
a transient program), it executes a "fork" function call (function 60H). This 
informs the system that a new program is being executed as a "subroutine" and 
amongst  other things, all of the currently open file handles are duplicated, 
so that  the new program will be using copies of the original handles, rather 
than the command interpreter's.

     If the transient program changes any of the file handles, by closing any 
existing ones  or opening  new ones, it will be the program's own set of file 
handles which are modified, the original set will remain unaltered. After the 
program  has terminated,  the command  interpreter executes a "join" function 
call (function  61H), passing  to it a process id which was returned from the 
original  "fork". This  tells the  system that the new program has terminated 
and so all its file handles can be thrown away. 

     Reference  counts are  kept of  how many copies of each handle there are 
which enables  the system  to tidy  up any  file handles  which are no longer 
needed  when a  program terminates. This ensures that the system will not run 
out of file handles because of badly behaved programs not closing them.

     These "fork"  and "join"  functions are  available for  user programs if 
they  find them  useful. In  addition to tidying up file handles, "join" will 
also free up any user allocated RAM segments which the program has not freed.

3.4   FILE INFO BLOCKS

     All  new MSX-DOS  functions that  act on  files on  disk can be passed a 
simple pointer  to a  null-terminated string (called an ASCIIZ string), which 
can  contain a  drive, path and unambiguous filename. These are typically the 
operations which a transient program will perform, often through a high level 
language interface. The Command Specification gives details of these.

     To any  of these  ASCIIZ functions,  a File  Info Block (FIB) may passed 
instead.  FIBs are  used for more complex operations such as the searching of 
directories for unknown files or sub-directories.

     A FIB  is a 64 byte area of the user's memory which contains information
about the directory entry on disk for a particular file or sub-directory. The 
information  in a FIB is filled in by the new MSX-DOS "find" functions ("find 
first entry"  (function 40H),  "find new entry" (function 42H) and "find next 
entry" (function 41H)). The format of a File Info Block is as follows:

     0 - Always 0FFh
 1..13 - Filename as an ASCIIZ string
    14 - File attributes byte
15..16 - Time of last modification
17..18 - Date of last modification
19..20 - Start cluster
21..24 - File size
    25 - Logical drive
26..63 - Internal information, must not be modified

     The 0FFh at the start of the fileinfo block must be there to distinguish 
it  from a  pathname string,  since some  functions can  take either  type of 
parameter.

     The  filename is  stored in a suitable format for directly printing, and 
is in  the form  of an  ASCIIZ string. Any spaces will have been removed, the 
filename  extension (if  present) will be preceded by a dot and the name will 
have been  uppercased. If  the entry  is a volume label then the name will be 
stored without the "." separator, with spaces left in and not uppercased.

     The  file attributes  byte is  a byte  of flags concerning the file. The 
format of this byte is:

Bit 0 - READ ONLY.  If set then the file cannot be written to or deleted, but 
        can be read, renamed or moved.

Bit 1 - HIDDEN  FILE. If  set then  the file  will only be found by the "Find 
        First"  function  if  the  "hidden  file"  bit is  set in  the search 
        attributes  byte.   All  the  commands  implemented  by  the  command 
        interpreter that access files and directories on disk can take a "/H" 
        option which allows the command to find hidden files.

Bit 2 - SYSTEM FILE.  As far as MSX-DOS functions are concerned, this bit has 
        exactly  the same  effect as  the "HIDDEN  FILE" bit  except that the 
        "Find New"  and "Create" function calls will not automatically delete 
        a  system  file.  None  of  the commands  implemented by  the command 
        interpreter allow system files to be accessed.

Bit 3 - VOLUME  NAME. If  set then this entry defines the name of the volume. 
        Can only  occur in  the root directory, and only once. All other bits 
        are ignored.

Bit 4 - DIRECTORY.  If set  then the  entry is  a sub-directory rather than a 
        file and so cannot be opened for reading and writing. Only the hidden 
        bit has any meaning for sub-directories.

Bit 5 - ARCHIVE BIT.  Whenever a file has been written to and closed this bit 
        is  set. This  bit can be examined by, for example, the XCOPY command 
        to determine whether the file has been changed.

Bit 6 - Reserved (always 0).

Bit 7 - DEVICE  BIT.  This  is  set  to  indicate that  the FIB  refers to  a 
        character device  (eg. "CON")  rather than  a disk  file. All  of the 
        other attributes bits are ignored.

     The time of last modification is encoded into two bytes as follows:

     Bits 15..11 - HOURS (0..23)
     Bits 10...5 - MINUTES (0..59)
     Bits  4...0 - SECONDS/2 (0..29)

     The  date of  last modification is encoded into two bytes as follows. If 
all bits are zero then there is no valid date set.

     Bits 15...9 - YEAR (0..99 corresponding to 1980..2079)
     Bits  8...5 - MONTH (1..12 corresponding to Jan..Dec)
     Bits  4...0 - DAY (1..31)

     The file  size is a 32 bit number stored with the lowest byte first, and
is zero for sub-directories.

     The logical drive is a single byte drive number, with 1 corresponding to 
A:, 2  to B:  etc. It  will never be zero, since if zero was specified in the 
original  function, this means the default drive and the driven number of the 
default drive will be filled in here.

     The  internal information  tells MSX-DOS where on the disk the directory
entry is stored. This enables functions to which the fileinfo block is passed 
to operate  on the  directory entry,  for example deleting it, renaming it or 
opening  it. Data  stored here  also enables  the "find  next entry" function 
(function 41H)  to carry  on the  search to  find the next matching file. The 
user should not access or modify the internal information at all.

     Fileinfo  blocks are  filled in  by the  "find first  entry", "find  new 
entry"  and  "find next  entry" MSX-DOS  functions. Each  of these  functions 
locates a  directory entry  and fills in the fileinfo block with the relevant 
information.

     In the  case of  "find first entry" a directory will be searched for the
first  entry which matches a given filename and which has suitable attributes 
(see the  Function Specification for details). "Find next entry" carries on a 
search  started by  a previous  "find first  entry" function  and updates the 
fileinfo block with the next matching entry.

     "Find new  entry" is just like "find first entry" except that instead of
looking  for a  matching entry,  it will  create a  new one and then return a 
fileinfo block just as if "find first" had found it.

     Having created  a fileinfo block using one of the "find" functions there 
are  two ways  in which  it can  be used.  The first way is to simply use the 
information which  it contains such as the filename and size. For example the 
"DIR" command simply prints out the information on the screen.

     The more interesting way of using a fileinfo block is to pass it back to 
another  MSX-DOS  function  in  order  to  carry  out some  operation on  the 
directory  entry. Many  of the  MSX-DOS functions  described in  the Function 
Specification take  a pointer  in register  DE which  can either  point to  a 
drive/path/file  string or a fileinfo block. In either case a particular file 
or directory is being specified for the function to act on.

     The  functions  which  can take  such a  parameter are  "Delete File  or 
Subdirectory"  (function 4DH),  "Rename file or Subdirectory" (function 4EH), 
"Move  File  or  Subdirectory"  (function  4FH),  "Get/Set  File  Attributes" 
(function 50H),  "Get/Set File  Date and  Time" (function 51H) and "Open File 
handle"  (function 43H).  All of  these carry out the obvious function on the 
specified file or directory.

     A fileinfo  block can  also be  passed to  a "find  first" or "find new"
function  in place  of the  drive/path/file string. In this case the fileinfo 
block must refer to a directory rather than a file and a filename string must 
also be  passed in register HL (typically null which is equivalent to "*.*"). 
The  directory specified  by the  fileinfo block will be searched for matches 
with the  filename, subject  to the usual attribute checking. This feature is 
necessary  for the command interpreter so that a command such as "DIR A:UTIL" 
can have the required action if UTIL is a directory.

3.5   ENVIRONMENT STRINGS

     MSX-DOS  maintains a list of "environment strings" in it's data segment. 
An environment  string is  a named item which has a value associated with it. 
Both  the  name  and  the  value  are  user-defined. Environment  strings are 
accessed  at  the  function  call  level  via  the  "Get  Environment String" 
(function 6BH), "Set Environment String" (function 6CH) and "Find Environment 
String" (function 6DH) functions.

     The name of an environment string is a non-null string consisting of any 
characters that  are valid in filenames. The name can be up to 255 characters 
long.  The characters of the name are upper-cased when the string is defined, 
although for name comparisons case is not significant.

     The value  of an  environment string  consists of  a string  of non-null 
characters  and  can  be  up  to  255  characters long.  If the  value of  an 
environment string is set to a null string, then the name is removed from the 
list of environment strings. Similarly, if the value of an environment string 
that  has not been defined is read, then a null string is returned. The value 
is not  upper-cased and  no interpretation is placed on the characters in the 
value string.

     When  a transient  program is loaded and executed from COMMAND2.COM, two 
special environment strings are set up, which it can read.

     An environment  string called  PARAMETERS is  set up to the command line 
not  including the  actual command name. This is similar to the one set up at 
80h for CP/M compatibility, but has not been upper-cased.

     Another environment string called PROGRAM is also set up and this is the 
whole  path used  to locate the program on disk. The drive is first, followed 
by the  path from  the root  and then the actual filename of the program. The 
drive,  path  and  filename  can  be separated  if desired  using the  "Parse 
Pathname" function call (function 5CH).

     The PROGRAM  environment string has several uses. The main use is that a 
program  can use  it to  load overlay files from the same directory as it was 
loaded from.  The last  item in  PROGRAM (ie. the actual program filename) is 
replaced  with the  name of  the overlay file, and then the new string can be 
passed to  any of  the new MSX-DOS 2 functions that take ASCIIZ strings (such 
as "Open File").

     Note  that  some  CP/M  programs  are  capable  of  loading and  running 
transient programs,  and in this case they obviously will not have set up the 
PROGRAM  and PARAMETERS  environment strings,  and they will in fact still be 
set up  from when  the CP/M  program was  loaded. If  a program wishes to use 
PROGRAM and PARAMETERS and still be loadable from a CP/M program, then it can 
look  at a  variable called "LOAD_FLAG", which is in page 0 at address 0037h. 
It is  set to  zero on  every MSX-DOS  2 function call but is set to non-zero 
immediately   before  a   transient  program   is  executed  by  the  command 
interpreter. Similarly,  if a  new transient  program has the ability to load 
other  transient programs  and it  sets up  PROGRAM and  PARAMETERS, then  it 
should also set LOAD_FLAG to non-zero.

     Another special environment string is one called APPEND. This can be set 
up  by the  user from  the command  interpreter and is used by the CP/M "Open 
File (FCB)"  function. When  this function  call is  done and the file is not 
found,  an alternative directory, specified by APPEND, is searched. It is not 
anticipated however  that new  transient programs will use this function call 
or the APPEND environment string.

     Several environment  strings are  set up by the command interpreter when 
it  starts up  and are altered by the user to control various system features 
and options,  and it  may be  useful for  transient programs  to read some of 
these.  For example,  it may be useful to read the PATH environment string or 
the DATE  and TIME  environment strings  if the  program prints out dates and 
times.   The  Command   Specification  contains   details  of  these  default 
environment strings.

3.6   FILE CONTROL BLOCKS

     It  is  not  anticipated  that  specially  written  MSX-DOS 2  transient 
programs  or MSX-DOS 1 or CP/M programs which are modified for MSX-DOS 2 will 
use the  CP/M-compatible FCB  functions, but  the format of the FCBs used for 
these  functions is given here for reference. This format is, of course, very 
similar to  the FCBs  used by  CP/M and  MSX-DOS 1 but the use of some of the 
fields within the FCB are different (though generally compatible).

     A basic  FCB is  33 bytes  long. This  type of  FCB can be used for file 
management  operations (delete,  rename etc.) and also for sequential reading 
and writing.  The random read and write functions use an extra 3 bytes on the 
end  of the  FCB to  store a  random record  number. The MSX-DOS 1 compatible 
block read  and write  functions also  use this  additional three (or in some 
cases four) bytes - see the Function Specification for details.

     The layout  of an  FCB is  given below. A general description of each of 
the fields is included here. The individual function description given in the 
Function  Specification details  of how the fields are used for each function 
where this is not obvious.

      00h  Drive number 1...8. 0 => default drive. Must be set up in all FCBs 
           used, never modified by MSX-DOS function calls (except "Open File" 
           if APPEND was used).

01h...08h  Filename, left  justified with  trailing blanks.  Can contain  "?" 
           characters   if  ambiguous   filename  is  allowed  (see  Function 
           Specification). When  doing comparisons case will be ignored. When 
           creating new files, name will be uppercased.

09h...0Bh  Filename  extension. Identical to filename. Note that bit-7 of the
           filename extension characters are NOT interpreted as flags as they 
           are in CP/M.

     0Ch   Extent number  (low byte).  Must be  set (usually  to zero) by the 
           transient program before open or create. It is used and updated by 
           sequential  read and write, and also set by random read and write. 
           This is compatible with CP/M and MSX-DOS 1.

     0Dh   File attributes. Set by "open", "create" or "find".

     0Eh   Extent  number (high  byte) for CP/M functions. Zeroed by open and 
           create. For sequential read and write it is used and updated as an 
           extension  to  the  extent  number  to  allow larger  files to  be 
           accessed.  Although  this  is  different  from  CP/M  it  does not 
           interfere with CP/Ms use of FCBs and is the same as MSX-DOS 1.

           Record size  (low byte)  for MSX-DOS 1 compatible block functions. 
           Must  be set  to the  required record  size before using the block 
           read or write functions. 

     0Fh   Record count  for CP/M  functions. Set  up by  open and create and 
           modified when necessary by sequential and random reads and writes. 
           This is the same as CP/M and MSX-DOS 1.

           Record  size (high byte) for MSX-DOS 1 compatible block functions. 
           Must be  set to  the required  record size  before using the block 
           read and write functions.

10h...13h  File size  in bytes,  lowest byte  first. File  size is exact, not 
           rounded  up to  128 bytes. This field is set up by open and create 
           and updated  when the file is extended by write operations. Should 
           not  be modified by the transient program as it is written back to 
           disk by  a close  function call. This is the same as MSX-DOS 1 but 
           different from CP/M which stores allocation information here.

14h...17h  Volume-id. This  is a  four byte number identifying the particular
           disk  which this FCB is accessing. It is set up by open and create 
           and  is  checked on  read, write  and close  calls. Should  not be 
           modified by  the program. Note that this is different from MSX-DOS 
           1  which stores  the date  and time  of last update here, and from 
           CP/M which stores allocation information.

18h...1Fh  Internal  information. These  bytes contain  information to enable 
           the file  to be located on the disk. Should not be modified at all 
           by  the transient  program. The  internal information kept here is 
           similar but  not identical  to that  kept by MSX-DOS 1 and totally 
           different from CP/M.

      20h  Current  record within  extent (0...127). Must be set (normally to 
           zero) by  the transient  program before  first sequential  read or 
           write. Used and modified by sequential read and write. Also set up 
           by random read and write. This is compatible with CP/M and MSX-DOS 
           1.

21h...24h  Random  record number,  low byte first. This field is optional, it
           is only  required if  random or block reads or writes are used. It 
           must  be set  up before  doing these  operations and is updated by 
           block read  and write but not by random read or write. Also set up 
           by the "set random record" function.

           For the  block operations, which are in MSX-DOS 1 but not in CP/M, 
           all  four bytes are used if the record size is less than 64 bytes, 
           and only  the first  three bytes are used if the record size is 64 
           bytes  or more.  For random  read and  write only  the first three 
           bytes  are  used  (implied  record  size  is 128  bytes). This  is 
           compatible with CP/M and with MSX-DOS 1.


    

Index

Vorige

Volgende