| Introduction | MTB Statements | File System | Compiler | Applications | Reference Guide | Index |
The Disk Operating System (DOS) employees four general-purpose CPU registers called AX, BX, CX, and DX. These registers contain two bytes each and are used in the Comet-to-DOS system function calls.
On many occasions, the two-byte registers are divided in half (for reference purposes). The "lower" half is referred to as the "L" portion and the "upper" half is referred to as the "H" portion. For example, the notation "AL" represents the lower byte of the AX register and "AH" represents the upper byte of the AX register.
The function calls documented herein contain references to the AX through DX registers (and their upper and lower halves in some cases). Typically, a function call requires that certain values be set prior to the function call itself.
Following the execution of the function call, some of the registers will contain return values. Since these return values (actually the contents of the registers) will be changed upon the execution of another function call, it is imperative that your program store the return value(s) for subsequent use.
For consistency of notation in this documentation, the register values set prior to each host system function call are referred to as the "entry" values. Likewise, the register values returned after the function call is executed are called "return" values.
Example:
The DOSFC function call can be used to create a DOS file. The function call requires three parameters, an AX value, a CX value, and the name of the file to be created.
The AX value must be set to "@3C00@" prior to executing the function. Hex 3C is the DOS command used to create a file. Also, CX must be set to null, and the file name must be supplied. A segment of the MTB program to accomplish this would look like this:
AX$ = "@3C00@" ! Set AX register to "CREATE" CX$ = "@0000@" ! Set CX register to null FILENAME$ = "A:\TEST" ! Set file name DOSFC(AX$,CX$,FILENAME$) EXCP=99 ! Execute function call
When this function call is executed, the file named "TEST" will be created on disk drive A:.
The DOSFC function call returns a value in the AX register. If the function is executed successfully, the AX register will contain the file's handle (a number assigned to the file by DOS; similar in concept to Comet's logical unit number).
Since the AX register can (and will) change, it is prudent to store the file's handle in a program variable for future use, as follows:
FILEHANDLE$ = AX$ ! Store file handle from AX$
Other function calls like read, write, and close require the file's handle. The above method ensures that the handle is stored for these subsequent purposes.
If the DOSFC function encounters an exception when it is executed, the exception branch is taken (in this case, the program will branch to statement-label 99) and the AX register will contain the DOS error code. Note: the Comet exception code will always by 27 when a DOS error is encountered.
In fact, only the 2nd byte of the AX register is of concern. The following program segment shows how to construct and print an error message for a DOS function call error. The DOS error code descriptions are maintained in a Comet file called "QERCOMET". Each DOS error code consists of the letter "D" followed by the two-byte DOS error code.
Note: To construct the proper key to the QERCOMET file, we'll need to convert the 2nd byte of the AX register to its ASCII equivalent and append the letter "D" to the front of it. We'll use the HEXASC function to do the conversion from hex to ASCII:
LENGTH 3 & LOCAL DOSCODE$ ! Define DOSCODE$ string
LENGTH 37 & LOCAL DOSMESSAGE$ ! Define message string
1000 FORMAT DOSMESSAGE$ ! Format for message
.
9999 OPEN (1) "QERCOMET" ! Open file
DOSCODE$ = "D"+HEXASC(SUB(A$,2,1)) ! Construct key
READ (1,1000) KEY=DOSCODE$ ! Read record
PRINT (0) "DOS error:";DOSCODE$ ! Display code
PRINT (0) DOSMESSAGE$ ! Display message
INPUT (0) "" ! Hold display
CLOSE (1) ! Close file
RUN "QMONITOR" ! Exit program