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