Section 3
BDOS Function Calls
This section describes each CP/M 3 system function, including the parameters a program must pass when calling the function, and the values the function returns to the program. The functions are arranged numerically for easy reference. You should be familiar with the BDOS calling conventions and other concepts presented in Section 2, before referencing this section.
BDOS FUNCTION 0: SYSTEM RESET
- Entry Parameters:
- Register
- C:
- 00H
The System Reset function terminates the calling program and returns control to the CCP via a warm start sequence (see Section 1.3.2). Calling this function has the same effect as a jump to location 0000H of Page Zero.
Note that the disk subsystem is not reset by System Reset under CP/M 3. The calling program can pass a return code to the CCP by calling Function 108, Get/Set Program Return Code, prior to making a System Reset call or jumping to location 0000H.
BDOS FUNCTION 1: CONSOLE INPUT
- Entry Parameters:
- Register
- C:
- 01H
- Returned Value:
- Register
- A:
- ASCII Character
The Console Input function reads the next character from the logical console, CONIN:, to register A. Graphic characters, along with carriage return, line-feed, and backspace, CTRL-H, are echoed to the console. Tab characters, CTR-I, are expanded in columns of 8 characters. CTRL-S, CTRL-Q, and CTRL-P are normally intercepted as described below. All other non-graphic characters are returned in register A but are not echoed to the console.
When the Console Mode is in the default state (see Section 2.2.1), Function 1 intercepts the stop scroll, CTRL-S, start scroll, CTRL-Q, and start/stop printer echo, CTRL-P, characters. Any characters that are typed following a CTRL-S and preceding a CTRL-Q are also intercepted. However, if start/stop scroll has been disabled by the Console Mode, the CTRL-S, CTRL-Q, and CTRL-P characters are not intercepted. Instead, they are returned in register A, but are not echoed to the console.
If printer echo has been invoked, all characters that are echoed to the console are also sent to the list device, LST:.
Function 1 does not return control to the calling program until a nonintercepted character is typed, thus suspending execution if a character is not ready.
BDOS FUNCTION 2: CONSOLE OUTPUT
- Entry Parameters:
- Registers
- C:
- 02H
- E:
- ASCII Character
The Console Output function sends the ASCII character from register E to the logical console device, CONOUT:. When the Console Mode is in the default state (see Section 2.2.1), Function 2 expands tab characters, CTRL-I, in columns of 8 characters, checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes characters to the logical list device, LST:, if printer echo, CTRL-P, has been invoked.
BDOS FUNCTION 3: AUXILIARY INPUT
- Entry Parameters:
- Register
- C:
- 03H
- Returned Value:
- Register
- A:
- ASCII Character
The Auxiliary Input function reads the next character from the logical auxiliary input device, AUXIN:, into register A. Control does not return to the calling program untiI the character is read.
BDOS FUNCTION 4: AUXILIARY OUTPUT
- Entry Parameters:
- Registers
- C:
- 04H
- E:
- ASCII Character
The Auxiliary Output function sends the ASCII character from register E to the logical auxiliary output device, AUXOUT:.
BDOS FUNCTION 5: LIST OUTPUT
- Entry Parameters:
- Registers
- C:
- 05H
- E:
- ASCII Character
The List Output function sends the ASCII character in register E to the logical list device, LST:.
BDOS FUNCTION 6: DIRECT CONSOLE I/O
- Entry Parameters:
- Registers
- C:
- 06H
- E:
- 0FFH (input/status) or
0FEH (status) or
0FDH (input) or
char (output)
- Returned Value:
- Register
- A:
- char or
status or
(no value)
CP/M 3 supports direct I/O to the logical console, CONIN:, for those specialized applications where unadorned console input and output is required. Use Direct Console I/O carefully because it bypasses all the normal control character functions.
Programs that perform direct I/O through the BIOS under previous releases of CP/M should be changed to use direct I/O so that they can be fully supported under future releases of MP/M and CP/M.
A program calls Function 6 by passing one of four different values in register E. The values and their meanings are summarized in Table 3-1.
Table 3-1. Function 6 Entry Parameters
- Register E value
- Meaning
- 0FFH
- Console input/status command returns an input character; if no character is ready, a value of zero is returned.
- 0FEH
- Console status command (On return, register A contains 0 if no character is ready; otherwise it contains 0FFH.)
- 0FDH
- Console input command, returns an input character; this function will suspend the calling process until a character is ready.
- ASCII character
- Function 6 assumes that register E contains a valid ASCII character and sends it to the console.
BDOS FUNCTION 7: AUXILIARY INPUT STATUS
- Entry Parameters:
- Register
- C:
- 07H
- Returned Value:
- Register
- A:
- Auxiliary Input Status
The Auxiliary Input Status function returns the value 0FFH in register A if a character is ready for input from the logical auxiliary input device, AUXIN:. If no character is ready for input, the value 00H is returned.
BDOS FUNCTION 8: AUXILIARY OUTPUT STATUS
- Entry Parameters:
- Register
- C:
- 08H
- Returned Value
- Register
- A:
- Auxiliary Output Status
The Auxiliary Output Status function returns the value 0FFH in register A if the logical auxiliary output device, AUXOUT:, is ready to accept a character for output. If the device is not ready for output, the value 00H is returned.
BDOS FUNCTION 9: PRINT STRING
- Entry Parameters:
- Registers
- C:
- 09H
- DE:
- String Address
The Print String function sends the character string addressed by register pair DE to the logical console, CONOUT:, until it encounters a delimiter in the string. Usually the delimiter is a dollar sign, $, but it can be changed to any other value by Function 110, Get/Set Output Delimiter. If the Console Mode is in the default state (see Section 2.2.1), Function 9 expands tab characters, CTRL-I, in columns of 8 characters. It also checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes to the logical list device, LST:, if printer echo, CTRL-P, has been invoked.
BDOS FUNCTION 10: READ CONSOLE BUFFER
- Entry Parameters:
- Registers
- C:
- 0AH
- DE:
- Buffer Address
- Returned Value:
- Console Characters in Buffer
The Read Console Buffer function reads a line of edited console input from the logical console, CONIN:, to a buffer that register pair DE addresses. It terminates input and returns to the calling program when it encounters a return, CTRL-M, or a line feed, CTRL-J, character. Function 10 also discards all input characters after the input buffer is filled. In addition, it outputs a bell character, CTRL-G, to the console when it discards a character to signal the user that the buffer is full. The input buffer addressed by DE has the following format:
![[console input buffer]](img/coninbuf.gif)
where mx is the maximum number of characters which the buffer holds, and nc is the number of characters placed in the buffer. The characters entered by the operator follow the nc value. The value mx must be set prior to making a Function 10 call and may range in value from 1 to 255. Setting mx to zero is equivalent to setting mx to one. The value nc is returned to the calling program and may range from zero to mx. If nc < mx, then uninitialized positions follow the last character, denoted by ?? in the figure. Note that a terminating return or line feed character is not placed in the buffer and not included in the count nc.
If register pair DE is set to zero, Function 10 assumes that an initialized input buffer is located at the current DMA address (see Function 26, Set DMA Address). This allows a program to put a string on the screen for the user to edit. To initialize the input buffer, set characters c1 through cn to the initial value followed by a binary zero terminator.
When a program calls Function 10 with an initialized buffer, Function 10 operates as if the user had typed in the string. When Function 10 encounters the binary zero terminator, it accepts input from the console. At this point, the user can edit the initialized string or accept it as it is by pressing the RETURN key. However, if the initialized string contains a return, CTRL-M, or a linefeed, CTRL-J, character, Function 10 returns to the calling program without giving the user the opportunity to edit the string.
The level of console editing supported by Function 10 differs for the banked and nonbanked versions of CP/M 3. Refer to the CPIM Plus (CP/M Version 3) Operating System User's Guide for a detailed description of console editing. In the nonbanked version, Function 10 recognizes the edit control characters summarized in Table 3-2.
Table 3-2. Edit Control Characters (Nonbanked CP/M 3)
- Character
- Edit Control Function
- rub/del
- Removes and echoes the last character; GENCPM can change this function to CTRL-H
- CTRL-C
- Reboots when at the beginning of line; the Console Mode can disable this function
- CTRL-E
- Causes physical end of line
- CTRL-H
- Backspaces one character position; GENCPM can change this function to rub/del
- CTRL-J
- (Line-feed) terminates input line
- CTRL-M
- (Return) terminates input line
- CTRL-P
- Echoes console output to the list device
- CTRL-R
- Retypes the current line after new line
- CTRL-U
- Removes current line after new line
- CTRL-X
- Backspaces to beginning of current line
The banked version of CP/M 3 expands upon the editing provided in the nonbanked version. The functionality of the two versions is similar when the cursor is positioned at the end of the line. However, in the banked version, the user can move the cursor anywhere in the current line, insert characters, delete characters, and perform other editing functions. In addition, the banked version saves the previous command line; it can be recalled when the current line is empty. Table 3-3 summarizes the edit control characters supported by Function 10 in the banked version of CP/M 3.
Table 3-3. Edit Control Characters (Banked CP/M 3)
- Character
- Edit Control Function
- rub/del
- Removes and echoes the last character if at the end of the line; otherwise deletes the character to the left of the current cursor position; GENCPM can change this function to CTRL-H.
- CTRL-A
- Moves cursor one character to the left.
- CTRL-B
- Moves cursor to the beginning of the line when not at the beginning; otherwise moves cursor to the end of the line.
- CTRL-C
- Reboots when at the beginning of line; the Console Mode can disable this function.
- CTRL-E
- Causes physical end-of-line; if the cursor is positioned in the middle of a line, the characters at and to the right of the cursor are displayed on the next line.
- CTRL-F
- Moves cursor one character to the right.
- CTRL-G
- Deletes the character at the current cursor position when in the middle of the line; has no effect when the cursor is at the end of the line.
- CTRL-H
- Backspaces one character position when positioned at the end of the line; otherwise deletes the character to the left of the cursor; GENCPM can change this function to rub/del.
- CTRL-J
- (Line-feed) terminates input; the cursor can be positioned anywhere in the line; the entire input line is accepted; sets the previous line buffer to the input line.
- CTRL-K
- Deletes all characters to the right of the cursor along with the character at the cursor.
- CTRL-M
- (Return) terminates input; the cursor can be positioned anywhere in the line; the entire input line is accepted; sets the previous line buffer to the input line.
- CTRL-P
- Echoes console output to the list device.
- CTRL-R
- Retypes the characters to the left of the cursor on the new line.
- CTRL-U
- Updates the previous line buffer to contain the characters to the left of the cursor; deletes current line, and advances to new line.
- CTRL-W
- Recalls previous line if current line is empty; otherwise moves cursor to end-of-line.
- CTRL-X
- Deletes all characters to the left of the cursor.
For banked systems, Function 10 uses the console width field defined in the System Control Block. If the console width is exceeded when the cursor is positioned at the end of the line, Function 10 automatically advances to the next line. The beginning of the line can be edited by entering a CTRL-R.
When a character is typed while the cursor is positioned in the middle of the line, the typed character is inserted into the line. Characters at and to the right of the cursor are shifted to the right. If the console width is exceeded, the characters disappear off the right of the screen. However, these characters are not lost. They reappear if characters are deleted out of the line, or if a CTRL-E is typed.
BDOS FUNCTION 11: GET CONSOLE STATUS
- Entry Parameters:
- Register
- C:
- 0BH
- Returned Value:
- Register
- A:
- Console Status
The Get Console Status function checks to see if a character has been typed at the logical console, CONIN:. If the Console Mode is in the default state (see Section 2.2.1), Function 11 returns the value 01H in register A when a character is ready. If a character is not ready, it returns a value of 00H.
If the Console Mode is in CTRL-C Only Status mode, Function 11 returns the value 01H in register A only if a CTRL-C has been typed at the console.
BDOS FUNCTION 12: RETURN VERSION NUMBER
- Entry Parameters:
- Register
- C:
- 0CH
- Returned Value:
- Register
- HL:
- Version Number
The Return Version Number function provides information that allows version independent programming. It returns a two-byte value in register pair HL: H contains 00H for CP/M and L contains 031H, the BDOS file system version number.
Function 12 is useful for writing applications programs that must run on multiple versions of CP/M and MP/M.
BDOS FUNCTION 13: RESET DISK SYSTEM
- Entry Parameters:
- Register C: 0DH
The Reset Disk System function restores the file system to a reset state where all the disk drives are set to read-write (see Functions 28 and 29), the default disk is set to drive A, and the default DMA address is reset to 0080H. This function can be used, for example, by an application program that requires disk changes during operation. Function 37, Reset Drive, can also be used for this purpose.
BDOS FUNCTION 14: SELECT DISK
- Entry Parameters:
- Registers
- C:
- 0EH
- E:
- Selected Disk
- Returned Value:
- Registers
- A:
- Error Flag
- H:
- Physical Error
The Select Disk function designates the disk drive named in register E as the default disk for subsequent BDOS file operations. Register E is set to 0 for drive A, 1 for drive B, and so on through 15 for drive P in a full 16-drive system. In addition, Function 14 logs in the designated drive if it is currently in the reset state. Logging-in a drive activates the drive's directory until the next disk system reset or drive reset operation.
FCBs that specify drive code zero (dr = 00H) automatically reference the currently selected default drive. FCBs with drive code values between 1 and 16, however, ignore the selected default drive and directly reference drives A through P.
Upon return, register A contains a zero if the select operation was successful. If a physical error was encountered, the select function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console, and the calling program is terminated. Otherwise, the select function returns to the calling program with register A set to 0FFH and register H set to one of the following physical error codes:
- 01
- Disk I/O Error
- 04
- Invalid drive
BDOS FUNCTION 15: OPEN FILE
- Entry Parameters:
- Registers
- C:
- 0FH
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Physical or Extended Error
The Open File function activates the FCB for a file that exists in the disk directory under the currently active user number or user zero. The calling program passes the address of the FCB in register pair DE, with byte 0 of the FCB specifying the drive, bytes 1 through 11 specifying the filename and filetype, and byte 12 specifying the extent. Usually, byte 12 of the FCB is initialized to zero.
If the file is password protected in Read mode, the correct password must be placed in the first eight bytes of the current DMA, or have been previously established as the default password (see Function 106). If the current record field of the FCB, cr, is set to 0FFH, Function 15 returns the byte count of the last record of the file in the cr field. You can set the last record byte count for a file with Function 30, Set File Attributes. Note that the current record field of the FCB, cr, must be zeroed by the calling program before beginning read or write operations if the file is to be accessed sequentially from the first record.
If the current user is non-zero, and the file to be opened does not exist under the current user number, the open function searches user zero for the file. If the file exists under user zero, and has the system attribute, t2', set, the file is opened under user zero. Write operations are not supported for a file that is opened under user zero in this manner.
If the open operation is successful, the user's FCB is activated for read and write operations. The relevant directory information is copied from the matching directory FCB into bytes d0 through dn of the FCB. If the file is opened under user zero when the current user number is not zero, interface attribute f8' is set to one in the user's FCB. In addition, if the referenced file is password protected in Write mode, and the correct password was not passed in the DMA, or did not match the default password, interface attribute f7' is set to one. Write operations are not supported for an activated FCB if interface attribute f7' or f8' is true.
When the open operation is successful, the open function also makes an access date and time stamp for the opened file when the following conditions are satisfied: the referenced drive has a directory label that requests Access date and time stamping, and the FCB extent number field is zero.
Upon return, the Open File function returns a directory code in register A with the value 00H if the open was successful, or 0FFH, 255 decimal, if the file was not found.
Register H is set to zero in both of these cases. If a physical or extended error was encountered, the Open File function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console and the program is terminated. Otherwise, the Open File function returns to the calling program with register A set to 0FFH, and register H set to one of the following physical or extended error codes:
- 01
- Disk I/O Error
- 04
- Invalid drive error
- 07
- File password error
- 09
- ? in the FCB filename or filetype field
BDOS FUNCTION 16: CLOSE FILE
- Entry Parameters:
- Registers
- C:
- 010H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Physical or Extended Error
The Close File function performs the inverse of the Open File function. The calling program passes the address of an FCB in register pair DE. The referenced FCB must have been previously activated by a successful Open or Make function call (see Functions 15 and 22). Interface attribute f5' specifies how the file is to be closed as shown below:
- f5' = 0
- Permanent close (default mode)
- f5' = 1
- Partial close
A permanent close operation indicates that the program has completed file operations on the file. A partial close operation updates the directory, but indicates that the file is to be maintained in the open state.
If the referenced FCB contains new information because of write operations to the FCB, the close function permanently records the new information in the referenced disk directory. Note that the FCB does not contain new information, and the directory update step is bypassed if only read or update operations have been made to the referenced FCB.
Upon return, the close function returns a directory code in register A with the value 00H if the close was successful, or 0FFH, 255 decimal, if the file was not found.
Register H is set to zero in both of these cases. If a physical or extended error is encountered, the close function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console, and the calling program is terminated. Otherwise, the close function returns to the calling program with register A set to 0FFH and register H set to one of the following physical error codes:
- 01
- Disk I/O error
- 02
- Read/only disk
- 04
- Invalid drive error
BDOS FUNCTION 17: SEARCH FOR FIRST
- Entry Parameters:
- Registers
- C:
- 011H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Physical Error
The Search For First function scans the directory for a match with the FCB addressed by register pair DE. Two types of searches can be performed. For standard searches, the calling program initializes bytes 0 through 12 of the referenced FCB, with byte 0 specifying the drive directory to be searched, bytes 1 through 11 specifying the file or files to be searched for, and byte 12 specifying the extent. Usually byte 12 is set to zero. An ASCII question mark, 63 decimal, 3F hex, in any of the bytes 1 through 12 matches all entries on the directory in the corresponding position. This facility, called ambiguous reference, can be used to search for multiple files on the directory. When called in the standard mode, the Search function scans for the first file entry in the specified directory that matches the FCB, and belongs to the current user number.
The Search For First function also initializes the Search For Next function. After the Search function has located the first directory entry matching the referenced FCB, the Search For Next function can be called repeatedly to locate all remaining matching entries. In terms of execution sequence, however, the Search For Next call must either follow a Search For First or Search For Next call with no other intervening BDOS disk-related function calls.
If byte 0 of the referenced FCB is set to a question mark, the Search function ignores the remainder of the referenced FCB, and locates the first directory entry residing on the current default drive. All remaining directory entries can be located by making multiple Search For Next calls. This type of search operation is not usually made by application programs, but it does provide complete flexibility to scan all current directory values. Note that this type of search operation must be performed to access a drive's directory label (see Section 2.3.6).
Upon return, the Search function returns a Directory Code in register A with the value 0 to 3 if the search is successful, or 0FFH, 255 decimal, if a matching directory entry is not found. Register H is set to zero in both of these cases. For successful searches, the current DMA is also filled with the directory record containing the matching entry, and the relative starting position is A * 32 (that is, rotate the A register left 5 bits, or ADD A five times). Although it is not usually required for application programs, the directory information can be extracted from the buffer at this position.
If the directory has been initialized for date and time stamping by INITDIR, then an SFCB resides in every fourth directory entry, and successful Directory Codes are restricted to the values 0 to 2. For successful searches, if the matching directory record is an extent zero entry, and if an SFCB resides at offset 96 within the current DMA, contents of (DMA Address + 96) = 021H, the SFCB contains the date and time stamp information, and password mode for the file. This information is located at the relative starting position of 97 + (A * 10) within the current DMA in the following format:
- 0 - 3
- Create or Access Date and Time Stamp Field
- 4 - 7
- Update Date and Time Stamp Field
- 8
- Password Mode Field
(Refer to Section 2.3.8 for more information on SFCBs.)
If a physical error is encountered, the Search function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console, and the calling program is terminated. Otherwise, the Search function returns to the calling program with register A set to 0FFH, and register H set to one of the following physical error codes:
- 01
- Disk I/O error
- 04
- Invalid drive error
BDOS FUNCTION 18: SEARCH FOR NEXT
- Entry Parameters:
- Register
- C:
- 012H
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Physical Error
The Search For Next function is identical to the Search For First function, except that the directory scan continues from the last entry that was matched. Function 18 returns a Directory code in register A, analogous to Function 17.
Note: in execution sequence, a Function 18 call must follow either a Function 17 or another Function 18 call with no other intervening BDOS disk-related function calls.
BDOS FUNCTION 19: DELETE FILE
- Entry Parameters:
- Registers
- C:
- 013H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Extended or Physical Error
The Delete File function removes files or XFCBs that match the FCB addressed in register pair DE. The filename and filetype can contain ambiguous references, that is, question marks in bytes f1 through t3, but the dr byte cannot be ambiguous, as it can in the Search and Search Next functions. Interface attribute f5' specifies the type of delete operation that is performed.
- f5' = 0
- Standard Delete (default mode)
- f5' = 1
- Delete only XFCBs
If any of the files that the referenced FCB specify are password protected, the correct password must be placed in the first eight bytes of the current DMA buffer, or have been previously established as the default password (see Function 106).
For standard delete operations, the Delete function removes all directory entries belonging to files that match the referenced FCB. All disk directory and data space owned by the deleted files is returned to free space, and becomes available for allocation to other files. Directory XFCBs that were owned by the deleted files are also removed from the directory. If interface attribute f5' of the FCB is set to 1, Function 19 deletes only the directory XFCBs that match the referenced FCB.
Note: if any of the files that match the input FCB specification fail the password check, or are Read-Only, then the Delete function does not delete any files or XFCBS. This applies to both types of delete operations.
In nonbanked systems, file passwords and XFCBs are not supported. Thus, if the Delete function is called with interface attribute f5' set to true, the Delete function performs no action but returns with register A set to zero.
Upon return, the Delete function returns a Directory Code in register A with the value 0 if the delete is successful, or 0FFH, 255 decimal, if no file that matches the referenced FCB is found. Register H is set to zero in both of these cases. If a physical, or extended error is encountered, the Delete function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console and the calling program is terminated. Otherwise, the Delete function returns to the calling program with register A set to 0FFH and register H set to one of the following physical or extended error codes:
- 01
- Disk I/O error
- 02
- Read-Only disk
- 03
- Read-Only file
- 04
- Invalid drive error
- 07
- File password error
BDOS FUNCTION 20: READ SEQUENTIAL
- Entry Parameters:
- Registers
- C:
- 014H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Error Code
- H:
- Physical Error
The Read Sequential function reads the next 1 to 128 128-byte records from a file into memory beginning at the current DMA address. The BDOS Multi-Sector Count (see Function 44) determines the number of records to be read. The default is one record. The FCB addressed by register pair DE must have been previously activated by an Open or Make function call.
Function 20 reads each record from byte cr of the extent, then automatically increments the cr field to the next record position. If the cr field overflows, then the function automatically opens the next logical extent and resets the cr field to 0 in preparation for the next read operation. The calling program must set the cr field to 0 following the Open call if the intent is to read sequentially from the beginning of the file.
Upon return, the Read Sequential function sets register A to zero if the read operation is successful. Otherwise, register A contains an error code identifying the error as shown below:
- 01
- Reading unwritten data (end-of-file)
- 09
- Invalid FCB
- 10
- Media change occurred
- 255
- Physical Error; refer to register H
Error Code 01 is returned if no data exists at the next record position of the file. Usually, the no data situation is encountered at the end of a file. However, it can also occur if an attempt is made to read a data block that has not been previously written, or an extent which has not been created. These situations are usually restricted to files created or appended with the BDOS random write functions (see Functions 34 and 40).
Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call that returns an error.
Error Code 10 is returned if a media change occurs on the drive after the referenced FCB is activated by a BDOS Open, or Make Call.
Error Code 255 is returned if a physical error is encountered and the BDOS error mode is Return Error mode, or Return and Display Error mode (see Function 45). If the error mode is the default mode, a message identifying the physical error is displayed at the console, and the calling program is terminated. When a physical error is returned to the calling program, register H contains one of the following error codes:
- 01
- Disk I/O error
- 04
- Invalid drive error
On all error returns except for physical error returns, A = 255, Function 20 sets register H to the number of records successfully read before the error is encountered. This value can range from 0 to 127 depending on the current BDOS Multi-Sector Count. It is always set to zero when the Multi-Sector Count is equal to one.
BDOS FUNCTION 21: WRITE SEQUENTIAL
- Entry Parameters:
- Registers
- C:
- 015H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Error Code
- H:
- Physical Error
The Write Sequential function writes 1 to 128 128-byte data records, beginning at the current DMA address into the file named by the FCB addressed in register pair DE. The BDOS Multi-Sector Count (see Function 44) determines the number of 128 byte records that are written. The default is one record. The referenced FCB must have been previously activated by a BDOS Open or Make function call.
Function 21 places the record into the file at the position indicated by the cr byte of the FCB, and then automatically increments the cr byte to the next record position. If the cr field overflows, the function automatically opens, or creates the next logical extent, and resets the cr field to 0 in preparation for the next write operation.
If Function 21 is used to write to an existing file, then the newly written records overlay those already existing in the file. The calling program must set the cr field to 0 following an Open or Make call if the intent is to write sequentially from the beginning of the file.
Function 21 makes an Update date and time for the file if the following conditions are satisfied: the referenced drive has a directory label that requests date and time stamping, and the file has not already been stamped for update by a previous Make or Write function call.
Upon return, the Write Sequential function sets register A to zero if the write operation is successful. Otherwise, register A contains an error code identifying the error as shown below:
- 01
- No available directory space
- 02
- No available data block
- 09
- Invalid FCB
- 10
- Media change occurred
- 255
- Physical Error : refer to register H
Error Code 01 is returned when the write function attempts to create a new extent that requires a new directory entry, and no available directory entries exist on the selected disk drive.
Error Code 02 is returned when the write command attempts to allocate a new data block to the file, and no unallocated data blocks exist on the selected disk drive.
Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call that returns an error.
Error Code 10 is returned if a media change occurs on the drive after the referenced FCB is activated by a BDOS Open or Make call.
Error Code 255 is returned if a physical error is encountered and the BDOS error mode is Return Error mode, or Return and Display Error mode (see Function 45). If the error mode is the default mode, a message identifying the physical error is displayed at the console, and the calling program is terminated. When a physical error is returned to the calling program, register H contains one of the following error codes:
- 01
- Disk I/O error
- 02
- Read-Only disk
- 03
- Read-Only file or
File open from user 0 when the current user number is non-zero or
File password protected in Write mode - 04
- Invalid drive error
On all error returns, except for physical error returns, A = 255, Function 21 sets register H to the number of records successfully written before the error was encountered. This value can range from 0 to 127 depending on the current BDOS MultiSector Count. It is always set to zero when the Multi-Sector Count is set to one.
BDOS FUNCTION 22: MAKE FILE
- Entry Parameters:
- Registers
- C:
- 016H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Physical or Extended Error
The Make File function creates a new directory entry for a file under the current user number. It also creates an XFCB for the file if the referenced drive has a directory label that enables password protection on the drive, and the calling program assigns a password to the file.
The calling program passes the address of the FCB in register pair DE, with byte 0 of the FCB specifying the drive, bytes 1 through 11 specifying the filename and filetype, and byte 12 set to the extent number. Usually, byte 12 is set to zero. Byte 32 of the FCB, the cr field, must be initialized to zero, before or after the Make call, if the intent is to write sequentially from the beginning of the file.
Interface attribute f6' specifies whether a password is to be assigned to the created file.
- f6' = 0
- Do not assign password (default)
- f6' = 1
- Assign password to created file
When attribute f6' is set to 1, the calling program must place the password in the first 8 bytes of the current DMA buffer, and set byte 9 of the DMA buffer to the password mode (see Function 102). Note that the Make function only interrogates interface attribute f6' if passwords are activated on the referenced drive. In nonbanked systems, file passwords are not supported, and attribute f6' is never interrogated. The Make function returns with an error if the referenced FCB names a file that currently exists in the directory under the current user number.
If the Make function is successful, it activates the referenced FCB for file operations by opening the FCB, and initializes both the directory entry and the referenced FCB to an empty file. It also initializes all file attributes to zero. In addition, Function 22 makes a Creation date and time stamp for the file if the following conditions are satisfied: the referenced drive has a directory label that requests Creation date and time stamping and the FCB extent number field is equal to zero. Function 22 also makes an Update stamp if the directory label requests update stamping and the FCB extent field is equal to zero.
If the referenced drive contains a directory label that enables password protection, and if interface attribute f6' has been set to 1, the Make function creates an XFCB for the file. In addition, Function 22 also assigns the password, and password mode placed in the first nine bytes of the DMA, to the XFCB.
Upon return, the Make function returns a directory code in register A with the value 0 if the make operation is successful, or 0FFH, 255 decimal, if no directory space is available. Register H is set to zero in both of these cases. If a physical or extended error is encountered, the Make function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console, and the calling program is terminated. Otherwise, the Make function returns to the calling program with register A set to 0FFH, and register H set to one of the following physical or extended error codes:
- 01
- Disk I/O error
- 02
- Read-Only disk
- 04
- Invalid drive error
- 08
- File already exists
- 09
- ? in filename or filetype field
BDOS FUNCTION 23: RENAME FILE
- Entry Parameters:
- Registers
- C:
- 017H
- DE:
- FCB Address
- Returned Value:
- Registers
- A:
- Directory Code
- H:
- Physical or Extended Error
The Rename function uses the FCB, addressed by register pair DE, to change all directory entries of the file specified by the filename in the first 16 bytes of the FCB to the filename in the second 16 bytes. If the file specified by the first filename is password protected, the correct password must be placed in the first eight bytes of the current DMA buffer, or have been previously established as the default password (see Function 106). The calling program must also ensure that the filenames specified in the FCB are valid and unambiguous, and that the new filename does not already exist on the drive. Function 23 uses the dr code at byte 0 of the FCB to select the drive. The drive code at byte 16 of the FCB is ignored.
Upon return, the Rename function returns a Directory Code in register A with the value 0 if the rename is successful, or 0FFH, 255 decimal, if the file named by the first filename in the FCB is not found. Register H is set to zero in both of these cases. If a physical or extended error is encountered, the Rename function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console and the program is terminated. Otherwise, the Rename function returns to the calling program with register A set to 0FFH and register H set to one of the following physical or extended error codes:
- 01
- Disk I/O error
- 02
- Read-Only disk
- 03
- Read-Only file
- 04
- Invalid drive error
- 07
- File password error
- 08
- File already exists
- 09
- ? in filename or filetype field
BDOS FUNCTION 24: RETURN LOGIN VECTOR
- Entry Parameters:
- Register
- C:
- 018H
- Returned Value:
- Register
- HL:
- Login Vector
Function 24 returns the login vector in register pair HL. The login vector is a 16-bit value with the least significant bit of L corresponding to drive A, and the high-order bit of H corresponding to the 16th drive, labelled P. A 0 bit indicates that the drive is not on-line, while a 1 bit indicates the drive is active. A drive is made active by either an explicit BDOS Select Disk call, number 14, or an implicit selection when a BDOS file operation specifies a non-zero dr byte in the FCB. Function 24 maintains compatibilty with earlier releases since registers A and L contain the same values upon return.
BDOS FUNCTION 25: RETURN CURRENT DISK
- Entry Parameters:
- Register
- C:
- 019H
- Returned Value:
- Register
- A:
- Current Disk
Function 25 returns the currently selected default disk number in register A. The disk numbers range from 0 through 15 corresponding to drives A through P.
BDOS FUNCTION 26: SET DMA ADDRESS
- Entry Parameters:
- Registers
- C:
- 01AH
- DE:
- DMA Address
DMA is an acronym for Direct Memory Address, which is often used in connection with disk controllers that directly access the memory of the computer to transfer data to and from the disk subsystem. Under CP/M 3, the current DMA is usually defined as the buffer in memory where a record resides before a disk write, and after a disk read operation. If the BDOS Multi-Sector Count is equal to one (see Function 44), the size of the buffer is 128 bytes. However, if the BDOS Multi-Sector Count is greater than one, the size of the buffer must equal N * 128, where N equals the Multi-Sector Count.
Some BDOS functions also use the current DMA to pass parameters, and to return values. For example, BDOS functions that check and assign file passwords require that the password be placed in the current DMA. As another example, Function 46, Get Disk Free Space, returns its results in the first 3 bytes of the current DMA. When the current DMA is used in this context, the size of the buffer in memory is determined by the specific requirements of the called function.
When a transient program is initiated by the CCP, its DMA address is set to 0080H. The BDOS Reset Disk System function, Function 13, also sets the DMA address to 0080H. The Set DMA function can change this default value to another memory address. The DMA address is set to the value passed in the register pair DE. The DMA address remains at this value until it is changed by another Set DMA Address, or Reset Disk System call.
BDOS FUNCTION 27: GET ADDR(ALLOC)
- Entry Parameters:
- Register
- C:
- 01BH
- Returned Value:
- Register
- HL:
- ALLOC Address
CP/M 3 maintains an allocation vector in main memory for each active disk drive. Some programs use the information provided by the allocation vector to determine the amount of free data space on a drive. Note, however, that the allocation information might be inaccurate if the drive has been marked Read-Only.
Function 27 returns in register pair HL, the base address of the allocation vector for the currently selected drive. If a physical error is encountered when the BDOS error mode is one of the return modes (see Function 45), Function 27 returns the value 0FFFFH in the register pair HL.
In banked CP/M 3 systems, the allocation vector can be placed in bank zero. In this case, a transient program cannot access the allocation vector. However, the BDOS function, Get Disk Free Space (Function 46), can be used to directly return the number of free 128-byte records on a drive. The CP/M 3 utilities that display a drive's free space, DIR and SHOW, use Function 46 for that purpose.
BDOS FUNCTION 28: WRITE PROTECT DISK
- Entry Parameters:
- Register
- C:
- 01CH
The Write Protect Disk function provides temporary write protection for the currently selected disk by marking the drive as Read-Only. No program can write to a disk that is in the Read-Only state. A drive reset operation must be performed for a Read-Only drive to restore it to the Read-Write state (see Functions 13 and 37).
BDOS FUNCTION 29: GET READ-ONLY VECTOR
- Entry Parameters:
- Register
- C:
- 01DH
- Returned Value:
- Register
- HL:
- R/O Vector Value
Function 29 returns a bit vector in register pair HL that indicates which drives have the temporary Read-Only bit set. The Read-Only bit can be set only by a BDOS Write Protect Disk call.
The format of the bit vector is analogous to that of the login vector returned by Function 24. The least significant bit corresponds to drive A, while the most significant bit corresponds to drive P.
Continue in...
Top of this document
Index
Last part of Section 3
Section 4
Section 0
Main