MSX-DOS 2.20 functions [5/5] 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. |