.bp odd .pn 23 .cs 5 .mt 5 .mb 6 .pl 66 .ll 65 .po 10 .hm 2 .fm 2 .ft All Information Presented Here is Proprietary to Digital Research .he .ce 2 .tc 4 Basic Disk Operating System Functions .sh Section 4 .sp .sh Basic Disk Operating System (BDOS) Functions .qs .he CP/M-8000 Programmer's Guide 4 BDOS Functions .sp .pp 5 To access a file or a drive, to output characters to the console, or to reset the system, your program must access the CP/M-8000 file system through the Basic Disk Operating System (BDOS). The BDOS provides functions that allow your program to perform these tasks. Table 4-1 summarizes the BDOS functions. .sp 2 .ce .sh Table 4-1. CP/M-8000 BDOS Functions .qs .sp .ix BDOS functions .in 1 .nf F# Function Type .sp 0 System Reset System/Program Control 1 Console Input Character I/O, Console Operation 2 Console Output Character I/O, Console Operation 3 Auxiliary Input* Character I/O, Additional Serial I/O 4 Auxiliary Output* Character I/O, Additional Serial I/O 5 List Output Character I/O, Additional Serial I/O 6 Direct Console I/O Character I/O, Console Operation 7 Get I/O Byte* I/O Byte 8 Set I/O Byte* I/O Byte 9 Print String Character I/O, Console Operation 10 Read Console Buffer Character I/O, Console Operation 11 Get Console Status Character I/O, Console Operation 12 Return Version Number System Control 13 Reset Disk System Drive 14 Select Disk Drive 15 Open File File Access 16 Close File File Access 17 Search for First File Access 18 Search for Next File Access 19 Delete File File Access 20 Read Sequential File Access 21 Write Sequential File Access 22 Make File File Access 23 Rename File File Access 24 Return Login Vector Drive 25 Return Current Disk Drive 26 Set DMA Address File Access 28 Write Protect Disk Drive 29 Get Read-Only Vector Drive 30 Set File Attributes File Access 31 Get Disk Parameters Drive 32 Set/Get User Code System/Program Control 33 Read Random File Access 34 Write Random File Access 35 Compute File Size File Access * Must be implemented in the BIOS .bp .in 0 .fi .ce .sh Table 4-1. (continued) .qs .sp .in 1 .nf F# Function Type .sp 36 Set Random Record File Access 37 Reset Drive Drive 40 Write Random With File Access Zero Fill 46 Get Disk Free Space Drive 47 Chain To Program System/Program Control 48 Flush Buffers System/Program Control 50 Direct BIOS Call System/Program Control 59 Program Load System/Program Control 61 Set Exception Vector Exception 62 Set Supervisor State Exception 63 Get/Set TPA Limits Exception .in 0 .fi .sp 2 .tc 4.1 BDOS Functions and Parameters .he CP/M-86K Programmer's Guide 4.1 BDOS Functions .sh 4.1 BDOS Functions and Parameters .qs .pp To invoke a BDOS function, you must specify one or more parameters. Each BDOS function is identified by a number, which is the first parameter you must specify. The function number is loaded in register R5. Some functions require a second parameter, which is loaded, depending on its size, in word register R7 or longword register RR6. Byte parameters are passed as 16-bit words. The low order byte contains the data, and the high order byte should be zeroed. For example, the second parameter for the Console Output Function (2) is an ASCII character, which is a byte parameter. The character is loaded in the low order byte of R7. Some BDOS functions return a value, which is passed in register R7. The hexadecimal value FFFF is returned in register R7 when you specify an invalid function number in your program. Table 4-2 illustrates the syntax and summarizes the registers that BDOS functions use. .ix BDOS parameters .sp 2 .ce .sh Table 4-2. BDOS Parameter Summary .sp .in 13 .nf BDOS Parameter Register .sp Function Number R5 Word Parameter R7 Longword Parameter RR6 Return Value, if any R7 .fi .in 0 .sp 2 .tc 4.1.1 Invoking BDOS Functions .sh 4.1.1 Invoking BDOS Functions .qs .pp After the parameters for a function are loaded in the appropriate registers, the program must specify a SC #2 (system call) instruction to access the BDOS and invoke the function. The example below illustrates the assembler syntax required to invoke the Console Output Function (2). .ix BDOS functions, invoking .sp .nf ld r5,#2 ;Moves the function number to R5 .sp ld r7,#'U' ;Moves the ASCII character upper-case U ;to R7 .sp sc #2 ;Accesses the BDOS to invoke the function. .sp .fi .pp The example above outputs the ASCII character upper-case U to the console. The assembler moves instructions load register R5 with the number 2 for the BDOS Console Output Function and register R7 with the ASCII character upper-case U. A pair of single ('') or double ("") quotation marks must enclose an ASCII character. The SC #2 instruction invokes the BDOS Output Console Function, which echos the character on the console's screen. .ix Invoking BDOS Functions .ix SC #2 Instruction .ix BDOS output console function .sp 2 .he CP/M-8000 Programmer's Guide 4.1 BDOS Functions .tc 4.1.2 Organization Of BDOS Functions .ix BDOS Functions, organization of .sh 4.1.2 Organization Of BDOS Functions .qs .pp The parameters and operation performed by each BDOS function are described in the following sections. Each BDOS function is categorized according to the function it performs. The categories are listed below. .sp .in 3 .nf o File Access o Drive Access o Character I/O o System/Program Control o Exception .fi .in 0 .pp As you read the description of the functions, notice that some functions require an address parameter designating the starting location of the direct memory access (DMA) buffer or file control block (FCB). The DMA buffer is an area in memory where a 128-byte record resides before a disk write function and after a disk read operation. Functions often use the DMA buffer to obtain or transfer data. The FCB is a 33- or 36-byte data structure that file access functions use. The FCB is described in Section 4.2.1. .sp 2 .he CP/M-8000 Programmer's Guide 4.2 File Access Functions .tc 4.2 File Access Functions .sh 4.2 File Access Functions .qs .ix file access functions .pp This section describes file access functions that create, delete, search for, read, and write files. They include the functions listed in Table 4-3. .bp .ce .sh Table 4-3. File Access Functions .sp .in 1 .nf Function Function Number .qs .sp Open File 15 .sp Close File 16 .sp Search For First 17 .sp Search For Next 18 .sp Delete File 19 .sp Read Sequential 20 .sp Write Sequential 21 .sp Make File 22 .sp Rename File 23 .sp Set DMA Address 26 .sp Read Random 33 .sp Write Random 34 .sp Compute File Size 35 .sp Write Random With Zero Fill 40 .fi .in 0 .sp 2 .tc 4.2.1 A File Control Block (FCB) .sh 4.2.1 A File Control Block (FCB) .qs .pp Most of the file access functions in Table 4-3 require the address of a File Control Block (FCB). A FCB is a 33- or 36-byte data structure that provides file access information. The FCB can be 33 or 36 bytes when a file is accessed sequentially, but it must be 36 bytes when a file is accessed randomly. The last three bytes in the 36-byte FCB contain the random record number, which is used by random I/O functions and the Compute File Size Function (35). The starting location of a FCB must be an even-numbered address. The format of a FCB and definitions of each of its fields are below. .bp .nf Field dr f1 f2 ... f8 t1 t2 t3 ex s1 s2 rc d0 ... dn cr r0 r1 r2 .sp Byte 00 01 02 ... 08 09 10 11 12 13 14 15 16 ... 31 32 33 34 35 .sp .nf dr drive code (0 - 16) 0 => use default drive for file 1 => auto disk select drive A, 2 => auto disk select drive B, ... 16=> auto disk select drive P. f1...f8 contain the filename in ASCII upper-case. High bit should equal 0 when the file is opened. t1,t2,t3 contain the filetype in ASCII upper-case. The high bit should equal 0 when the file is opened. For the Set File Attributes Function (see Section 4.2.13), t1', t2', and t3' denote the high bit. The list below indicates which attributes are set when these bits are set and equal the value 1. t1' = 1 => Read-Only file t2' = 1 => SYS file t3' = 1 => Archive ex contains the current extent number, normally set to 00 by the user, but is in the range 0 - 31 (decimal) for file I/O s1 reserved for internal system use s2 reserved for internal system use, set to zero for Open (15), Make (22), Search (17,18) file functions. rc record count field, reserved for system use d0...dn filled in by CP/M, reserved for system use cr current record to be read or written; for a sequential read or write file operation, the program normally sets this field to zero to access the first record in the file r0,r1,r2 optional, contain random record number in the range 0-3FFFFH; bytes r0, r1, and r2 are a 24-bit value with the most significant byte r0 and the least significant byte r2. Random I/O functions use the random record number in this field. .fi .pp For users of other versions of CP/M, note that both CP/M-80 Version 2.2 and CP/M-8000 perform directory operations in a reserved area of memory that does not affect the DMA buffer contents, except for the Search For First (17) and Search For Next (18) Functions in which the directory record is copied to the current DMA buffer. .sp 2 .tc 4.2.2 File Processing Errors .sh 4.2.2 File Processing Errors .qs .ix file processing errors .pp When a program calls a BDOS function to process a file, an error condition can cause the BDOS to return one of five error messages to the console: .sp .in 3 .nf o CP/M Disk read error o CP/M Disk write error o CP/M Disk select error o CP/M Disk change error o CP/M Disk file error: ffffffff.ttt is read-only. .fi .in 0 .ix disk read error .ix disk write error .ix disk select error .ix disk change error .ix disk file error .sp .in 0 Except for the CP/M Disk file error, CP/M-8000 displays the error message at the console in the format: .sp .ti 8 "error message text" on drive x .sp The "error message text" is one of the error messages listed above. The variable x is a one-letter drive code that indicates the drive on which CP/M-8000 detects the error. CP/M-8000 displays the CP/M Disk file error in the format shown above. .pp When CP/M-8000 detects one of these errors, the BDOS traps it. CP/M-8000 displays a message indicating the error and, depending on the error, allows you to abort the program, retry the operation, or continue processing. Each of these errors and their options are described below. .ix read error .ix write error .pp CP/M issues a CP/M Disk read or write error when the BDOS receives a hardware error from the BIOS. The BDOS specifies BIOS read and write sector commands when the BDOS executes file-related system functions. If the BIOS read or write routine detects a hardware error, the BIOS returns an error code to the BDOS that results in CP/M-8000 displaying a disk read or write error message at your console. In addition to the error message, CP/M-8000 also displays the option message: .sp .nf Do you want to Abort (A), Retry (R), or Continue with bad data (C)? .fi .sp In response to the option message, you type one of the letters enclosed in parentheses and a RETURN. Each of these options is described below. .bp .ce .sh Table 4-4. Read-Write Error Message Response Options .qs .in 5 .sp .nf Option Action .fi .sp .ll 60 .in 18 .ti -10 A The A option or CTRL-C aborts the program and returns control to the CCP. CP/M-8000 returns the system prompt (>) preceded by the drive code. .sp .ti -10 R The R option retries the operation that caused the error. For example, it rereads or rewrites the sector. If the operation succeeds, program execution continues as if no error occurred. However, if the operation fails, the error message and option message is displayed again. .sp .ti -10 C The C option ignores the error that occurred and continues program execution. The C option is not an appropriate response for all types of programs. Program execution should not be continued in some cases. For example, if you are updating a data base and receive a read or write error but continue program execution, you can corrupt the index fields and the entire data base. For other programs, continuing program execution is recommended. For example, when you transfer a long text file and receive an error because one sector is bad, you can continue transferring the file. After the file is transferred, review the file. Using an editor, add the data that was not transferred due to the bad sector. .in 0 .ll 65 .sp .pp Any response other than an A, R, C, or CTRL-C is invalid. The BDOS reissues the option message if you enter any other response. .pp The CP/M Disk select error occurs when you select a disk but you receive an error due to one of the conditions below. .sp .in 3 .nf o You specified a disk drive not supported by the BIOS. o The BDOS receives an error from the BIOS. o You specified a disk drive outside the range A through P. .sp .mt 4 .hm 1 .in 0 .fi Before the BDOS issues a read or write function to the BIOS, the BDOS issues a disk select function to the BIOS. If the BIOS does not support the drive specified in the function, or if an error occurs, the BIOS returns an error to the BDOS, which in turn, causes CP/M-8000 to display the disk select error at your console. If the error is caused by a BIOS error, CP/M-8000 returns the option message: .sp .in 8 Do you want to Abort (A) or Retry (R)? .sp .qi To select one of the options in the message, specify one of the letters enclosed in parentheses. The A option terminates the program and returns control to the CCP. The R option tries to select the disk again. If the disk select function fails, CP/M-8000 redisplays the disk select error message and the option message. .pp .mb 5 .fm 1 However, if the error is caused because you specify a disk drive outside the range A through P, only the CP/M Disk select error is displayed. CP/M-8000 aborts the program and returns control to the CCP. .pp Your console displays the CP/M Disk change error message when the BDOS detects the disk in the drive is not the same disk that was logged in previously. Your program cannot recover from this error. Your program terminates. CP/M-8000 returns program control to the CCP. .pp You log in a disk by accessing the disk or resetting the disk or disk system. The Select Disk Function (14) resets a disk. The Reset Disk System Function (13) resets the disk system. Files cannot be open when your program invokes either of these functions. .ix disk file error .pp You receive the CP/M Disk file error and option messages (shown below) if you call the BDOS to write to a file that is set to read-only status. Either a STAT command or the BDOS Set File Attributes Function (30) sets a file to read-only status. .sp .in 8 CP/M Disk file error: ffffffff.ttt is read-only. .sp Do you want to: Change it to read/write (C), or Abort (A)? .sp .qi The variable ffffffff.ttt in the error message denotes the filename and filetype. To select one of the options, specify one of the letters enclosed in parentheses. Each option is described below. .sp 2 .ce .sh Table 4-5. Disk File Error Response Options .qs .in 5 .sp .nf Option Action .fi .ll 60 .in 16 .sp .ti -8 C Changes the status of this file from read-only to read-write and continues executing the program that was being processed when this error occurred. .sp .mt 5 .hm 2 .ti -8 A Terminates execution of the program that was being processed and returns program control to the CCP. The status of the file remains read-only. If you enter a CTRL-C, it has the same effect as specifying the A option. .in 0 .ll 65 .sp .pp CP/M-8000 reprompts with the option message if you enter any response other than those described above. .mb 6 .fm 2 .nx fourb