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