ASCII, 01-09-94
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.
|
