The BDOS System Interface
This section describes the operating system services available to a transient program through the BDOS module of CP/M 3. The section begins by defining how a transient program calls BDOS functions, then discusses serial I/O for console, list and auxiliary devices, the file system, and Page Zero initialization.
BDOS Calling Conventions
CP/M 3 uses a standard convention for BDOS function calls. On entry to the BDOS, register C contains the BDOS function number, and register pair DE contains a byte or word value or an information address. BDOS functions return single-byte values in register A, and double-byte values in register pair HL. In addition, they return with register A equal to L, and register H equal to B. If a transient program makes a BDOS call to a nonsupported function number in the range of 0 to 127, the BDOS returns with register pair HL set to 0FFFFH. For compatibility with MP/M, the BDOS returns with register pair HL set to 0000H on nonsupported function numbers in the range of 128 to 255. Note that CP/M 2 returns with HL set to zero on all invalid function calls. CP/M 3's register passing conventions for BDOS function calls are consistent with the conventions used by the Intel PL/M systems programming language.
When a transient program makes a BDOS function call, the BDOS does not restore registers to their entry values before returning to the calling program. The responsibility for saving and restoring any critical register values rests with the calling program.
When the CCP loads a transient program, the LOADER module sets the stack pointer to a 16 level stack, and then pushes the address 0000H onto the stack. Thus, an immediate return to the system is equivalent to a jump to 0000H. However, most transient programs set up their own stack, and terminate execution by making a BDOS System Reset call (Function 0) or by jumping to location 0000H.
The following example illustrates how a transient program calls a BDOS function. This program reads characters continuously until it encounters an asterisk. Then it terminates execution by returning to the system.
bdos equ 0005h ;BDOS entry Point in Page Zero conin equ 1 ;BDOS console input function ; org 100h ;Base of Transient Program Area nextc: mvi c,conin call bdos ;Return character in A cpi '*' ;End of Processing? jnz nextc ;Loop if not ret ;Terminate Program end
BDOS Serial Device I/O
Under CP/M 3, serial device I/O is simply input to and output from simple devices such as consoles, line printers, and communications devices. These physical devices can be assigned the logical device names defined below:
If your system supports the BIOS DEVTBL function, the CP/M 3 DEVICE utility can display and change the assignment of logical devices to physical devices. DEVICE can also display the names and attributes of physical devices supported on your system. If your system does not support the DEVTBL entry point, then the logical to physical device assignments are fixed by the BIOS.
In general, BDOS serial I/O functions read and write an individual ASCII character, or character string to and from these devices, or test the device's ready status. For these BDOS functions, a string of characters is defined as zero to N characters terminated by a delimiter. A block of characters is defined as zero to N characters where N is specified by a word count field. The maximum value of N in both cases is limited only by available memory. The following list summarizes BDOS serial device I/O functions.
Read a character from CONIN:
CP/M 3 cannot run unless CONIN: and CONOUT: are assigned to a physical console. The remaining logical devices can remain unassigned. If a logical output device is not assigned to a physical device, an output BDOS call to the logical device performs no action. If a logical input device is not assigned to a physical device, an input BDOS call to the logical device typically returns a CTRL-Z (01AH), which indicates end-of-file. Note that these actions depend on your system's BIOS implementation.
BDOS Console I/O
Because a transient program's main interaction with its user is through the console, the BDOS supports many console I/O functions. Console I/O functions can be divided into four categories: basic console I/O, direct console I/O, buffered console input, and special console functions. Using the basic console I/O functions, programs can access the console device for simple input and output. The basic console I/O functions are:
The input function echoes the character to the console so that the user can identify the typed character. The output functions expand tabs in columns of eight characters. The basic I/O functions also monitor the console to stop and start console output scroll at the user's request. To provide this support, the console output functions make internal status checks for an input character before writing a character to the output device. The console input and console status functions also check the input character. If the user types a CTRL-S, these functions make an additional BIOS console input call. This input call suspends execution until a character is typed. If the typed character is not a CTRL-Q, an additional BIOS console input call is made. Execution and console scrolling resume when the user types a CTRL-Q.
When the BDOS is suspended because of a typed CTRL-S, it scans input for three special characters: CTRL-Q, CTRL-C, and CTRL-P. If the user types any other character, the BDOS echoes a bell character, CTRL-G, to the console, discards the input character, and continues the scan. If the user types a CTRL-C, the BDOS executes a warm start which terminates the calling program. If the user types a CTRL-P, the BDOS toggles the printer echo switch. The printer echo switch controls whether console output is automatically echoed to the list device, LST:. The BDOS signals when it turns on printer echo by sending a bell character to the console.
All basic console I/O functions discard any CTRL-Q or CTRL-P character that is not preceded by a CTRL-S character. Thus, BDOS function 1 cannot read a CTRL-S, CTRL-Q, or CTRL-P character. Furthermore, these characters are invisible to the console status function.
The second category of console I/O is direct console I/O. BDOS function 6 can provide direct console I/O in situations where unadorned console I/O is required. Function 6 actually consists of several sub-functions that support direct console input, output, and status checks. The BDOS does not filter out special characters during direct console I/O. The direct output sub-function does not expand tabs, and the direct input sub-function does not echo typed characters to the console.
The third category of console I/O accepts edited input from the console. The only function in this category, Function 10, Read Buffer Input, reads an input line from a buffer and recognizes certain control characters that edit the input. As an option, the line to be edited can be initialized by the calling program.
In the nonbanked version of CP/M 3, editing within the buffer is restricted to the last character on the line. That. is, to edit a character embedded in the line, the user must delete all characters that follow the erroneous character, correct the error, and then retype the remainder of the line. The banked version of CP/M 3 supports complete line editing in which characters can be deleted and inserted anywhere in the line. In addition, the banked version can also recall the previously entered line.
Function 10 also filters input for certain control characters. If the user types a CTRL-C as the first character in the line, Function 10 terminates the calling program by branching to the BIOS warm start entry point. A CTRL-C in any other position is simply echoed at the console. Function 10 also watches for a CTRL-P keystroke, and if it finds one at any position in the command line, it toggles the printer echo switch. Function 10 does not filter CTRL-S and CTRL-Q characters, but accepts them as normal input. In general, all control characters that Function 10 does not recognize as editing control characters, it accepts as input characters. Function 10 identifies a control character with a leading caret,^ , when it echoes the control character to the console. Thus, CTRL-C appears as ^C in a Function 10 command line on the screen.
The final category of console I/O functions includes special functions that modify the behavior of other console functions. These functions are:
Function 110 can get or set the current delimiter for Function 9, Print String. The delimiter is $, when a transient program begins execution. Function 109 gets or sets a 16-bit system variable called the Console Mode. The following list describes the bits of the Console Mode variable and their functions:
In conditional status mode, GET responds false to all status requests except for a status call preceded immediately by another status call. On the second call, GET responds with a true result. Thus, a program that spins on status to wait for a character is signaled that a character is ready on the second call. In addition, a program that makes status calls periodically to see if the user wants to stop is not signaled.
When a transient program begins execution, the Console Mode bits are normally set to zero. However, the CP/M 3 utility GENCOM can attach an RSX header to a COM file so that when it is loaded, the console mode bits are set differently. This feature allows you to modify a program's console I/O behavior without having to change the program.
Other Serial I/O
The BDOS supports single character output functions for the logical devices LST: and AUXOUT:, an input function for AUXIN:, and status functions for AUXIN: and AUXOUT:. A block output function is also supported for the LST: device. Unlike the console I/O functions, the BDOS does not intercept control characters or expand tabs for these functions. Note that AUXIN: and AUXOUT: replace the READER and PUNCH devices supported by earlier versions of CP/M.
BDOS File System
Transient programs depend on the BDOS file system to create, update, and maintain disk files. This section describes the capabilities of the BDOS file system in detail. You must understand the general features of CP/M 3 described in Section 1 before you can use the detail presented in this section.
The remaining introductory paragraphs define the four categories of BDOS file functions. This is followed by a review of file naming conventions and disk and file organization. The section then describes the data structure used by the BDOS file, and directory oriented functions: the File Control Block (FCB). Subsequent discussions cover file attributes, user numbers, directory labels and extended File Control Blocks (XFCBs), passwords, date and time stamping, blocking and deblocking, multi-sector I/O, disk reset and removable media, byte counts, and error handling. These topics are closely related to the BDOS file system. You must be familiar with the contents of Section 2 before attempting to use the BDOS functions described individually in Section 3.
The BDOS file system supports four categories of functions: file access functions, directory functions, drive related functions, and miscellaneous functions. The file access category includes functions to create a file, open an existing file, and close a file. Both the make and open functions activate the file for subsequent access by BDOS file access functions. The BDOS read and write functions are file access functions that operate either sequentially or randomly by record position. They transfer data in units of 128 bytes, which is the basic record size of the file system. The close function makes any necessary updates to the directory to permanently record the status of an activated file.
BDOS directory functions operate on existing file entries in a drive's directory. This category includes functions to search for one or more files, delete one or more files, truncate a file, rename a file, set file attributes, assign a password to a file, and compute the size of a file. The search and delete functions are the only BDOS functions that support ambiguous file references. All other directory and file related functions require a specific file reference.
The BDOS drive-related category includes functions that select the default drive, compute a drive's free space, interrogate drive status, and assign a directory label to a drive. A drive's directory label controls whether or not CP/M 3 enforces file password protection, or stamps files with the date and time. Note that the nonbanked version of CP/M 3 does not support file passwords.
The miscellaneous category includes functions to set the current DMA address, access and update the current user number, chain to a new program, and flush internal blocking/deblocking buffers. Also included are functions that set the BDOS multi-sector count, and the BDOS error mode. The BDOS multi-sector count determines the number of 128-byte records to be processed by BDOS read and write functions. It can range from 1 to 128. The BDOS error mode determines how the BDOS file system handles certain classes of errors.
Also included in the miscellaneous category are functions that call the BIOS directly, set a program return code, and parse filenames. If the LOADER RSX is resident in memory, programs can also make a BDOS function call to load an overlay. Another miscellaneous function accesses system variables in the System Control Block.
The following list summarizes the operations performed by the BDOS file system:
Disk System Reset
File Naming Conventions
Under CP/M 3, a file specification consists of four parts: the drive specifier, the filename field, the filetype field, and the file password field. The general format for a command line file specification is shown below:
The drive specifier field specifies the drive where the file is located. The filename and type fields identify the file. The password field specifies the password if a file is password protected.
The drive, type, and password fields are optional, and the delimiters :.; are required only when specifying their associated field. The drive specifier can be assigned a letter from A to P where the actual drive letters supported on a given system are determined by the BIOS implementation. When the drive letter is not specified, the current default drive is assumed.
The filename and password fields can contain one to eight non-delimiter characters. The filetype field can contain one to three non-delimiter characters. All three fields are padded with blanks, if necessary. Omitting the optional type or password fields implies a field specification of all blanks.
The CCP calls BDOS Function 152, Parse Filename, to parse file specifications from a command line. Function 152 recognizes certain ASCII characters as valid delimiters when it parses a file from a command line. The valid delimiters are shown in Table 2-1.
Table 2-1. Valid Filename Delimiters
Function 152 also excludes all control characters from the file fields, and translates all lower-case letters to upper-case.
Avoid using parentheses and the backslash character, \, in the filename and filetype fields because they are commonly used delimiters. Use asterisk and question mark characters, * and ?, only to make an ambiguous file reference. When Function 152 encounters an * in a filename or filetype field, it pads the remainder of the field with question marks. For example, a filename of X*.* is parsed to X???????.???. The BDOS search and delete functions treat a ? in the filename and type fields as follows: A ? in any position matches the corresponding field of any directory entry belonging to the current user number. Thus, a search operation for X???????.??? finds all the current user files on the directory beginning in X. Most other file related BDOS functions treat the presence of a ? in the filename or type field as an error.
It is not mandatory to follow the file naming conventions of CP/M 3 when you create or rename a file with BDOS functions. However, the conventions must be used if the file is to be accessed from a command line. For example, the CCP cannot locate a command file in the directory if its filename or type field contains a lower-case letter.
As a general rule, the filetype field names the generic category of a particular file, while the filename distinguishes individual files in each category. Although they are generally arbitrary, the following list of filetypes names some of the generic categories that have been established.
Disk and File Organization
The BDOS file system can support from one to sixteen logical drives. The maximum file size supported on a drive is 32 megabytes. The maximum capacity of a drive is determined by the data block size specified for the drive in the BIOS. The data block size is the basic unit in which the BDOS allocates disk space to files.
Table 2-2 displays the relationship between data block size and drive capacity.
Table 2-2. Logical Drive Capacity
Logical drives are divided into two regions: a directory area and a data area. The directory area contains from one to sixteen blocks located at the beginning of the drive. The actual number is set in the BIOS. This area contains entries that define which files exist on the drive. The directory entries corresponding to a particular file define those data blocks in the drive's data area that belong to the file. These data blocks contain the file's records. The directory area is logically subdivided into sixteen independent directories identified as user 0 through 15. Each independent directory shares the actual directory area on the drive. However, a file's directory entries cannot exist under more than one user number. In general, only files belonging to the current user number are visible in the directory.
Each disk file consists of a set of up to 262,144 128-byte records. Each record in a file is identified by its position in the file. This position is called the record's random record number. If a file is created sequentially, the first record has a position of zero, while the last record has a position one less than the number of records in the file. Such a file can be read sequentially in record position order beginning at record zero, or randomly by record position. Conversely, if a file is created randomly, records are added to the file by specified position. A file created in this way is called sparse if positions exist within the file where a record has not been written.
The BDOS automatically allocates data blocks to a file to contain its records on the basis of the record positions consumed. Thus, a sparse file that contains two records, one at position zero, the other at position 262,143, consumes only two data blocks in the data area. Sparse files can only be created and accessed randomly, not sequentially. Note that any data block allocated to a file is permanently allocated to the file until the file is deleted or truncated. These are the only mechanisms supported by the BDOS for releasing data blocks belonging to a file.
Source files under CP/M 3 are treated as a sequence of ASCII characters, where each line of the source file is followed by a carriage return line-feed sequence, 0DH followed by 0AH. Thus a single 128-byte record could contain several lines of source text. The end of an ASCII file is denoted by a CTRL-Z character, 01AH, or a real end of file, returned by the BDOS read operation. CTRL-Z characters embedded within machine code files such as COM files are ignored. The actual end-of-file condition returned by the BDOS is used to terminate read operations.
File Control Block Definition
The File Control Block, FCB, is a data structure that is set up and initialized by a transient program, and then used by any BDOS file access and directory functions called by the transient program. Thus the FCB is an important channel for information exchange between the BDOS and a transient program. For example, when a program opens a file, and subsequently accesses it with BDOS read and write record functions, the BDOS file system maintains the current file state and position within the program's FCB. Some BDOS functions use certain fields in the FCB for invoking special options. Other BDOS functions use the FCB to return data to the calling program. In addition, all BDOS random I/O functions specify the random record number with a 3-byte field at the end of the FCB.
When a transient program makes a file access or directory BDOS function call, register pair DE must address an FCB. The length of the FCB data area depends on the BDOS function. For most functions, the required length is 33 bytes. For random I/O functions, the Truncate File function, and the Compute File Size function, the FCB length must be 36 bytes. The FCB format is shown next.
For BDOS directory functions, the calling program must initialize bytes 0 through 11 of the FCB before issuing the function call. The Set Directory Label and Write File XFCB functions also require the calling program to initialize byte 12. The Rename File function requires the calling program to place the new filename and type in bytes 17 through 27.
BDOS open or make function calls require the calling program to intialize bytes 0 through 12 of the FCB before making the call. Usually, byte 12 is set to zero. In addition, if the file is to be processed from the beginning using sequential read or write functions, byte 32, cr, must be zeroed.
After an FCB is activated by an open or make operation, a program does not have to modify the FCB to perform sequential read or write operations. In fact, bytes 0 through 31 of an activated FCB should not be modified. However, random I/O functions require that a program set bytes 33 through 35 to the requested random record number prior to making the function call.
File directory entries maintained in the directory area of each disk have the same format as FCBs, excluding bytes 32 through 35, except for byte 0 which contains the file's user number. Both the Open File and Make File functions bring these entries, excluding byte 0, into memory in the FCB specified by the calling program. All read and write operations on a file must specify an FCB activated in this manner.
The BDOS updates the memory copy of the FCB during file processing to maintain the current position within the file. During file write operations, the BDOS updates the memory copy of the FCB to record the allocation of data to the file, and at the termination of file processing, the Close File function permanently records this information on disk. Note that data allocated to a file during file write operations is not completely recorded in the directory until the calling program issues a Close File call. Therefore, a program that creates or modifies files must close the files at the end of any write processing. Otherwise, data might be lost.
The BDOS Search and Delete functions support multiple or ambiguous file references. In general, a question mark in the filename, filetype, or extent field matches any value in the corresponding positions of directory FCBs during a directory search operation. The BDOS search functions also recognize a question mark in the drive code field, and if specified, they return all directory entries on the disk regardless of user number, including empty entries. A directory FCB that begins with 0E5H is an empty directory entry.
The high-order bits of the FCB filename, f1', ... , f8', and filetype, t2', t2', t3', fields are called attribute bits. Attributes bits are 1 bit Boolean fields where 1 indicates on or true, and 0 indicates off or false. Attribute bits indicate two kinds of attributes within the file system: file attributes and interface attributes.
The file attribute bits, f1' ...... f4' and t1', t2', t3', can indicate that a file has a defined file attribute. These bits are recorded in a file's directory FCBs. File attributes can be set or reset only by the BDOS Set File Attributes function. When the BDOS Make File function creates a file, it initializes all file attributes to zero. A program can interrogate file attributes in an FCB activated by the BDOS Open File function, or in directory FCBs returned by the BDOS Search For First and Search For Next functions.
Note: the BDOS file system ignores file attribute bits when it attempts to locate a file in the directory.
The file system defines the file attribute bits, t1', t2', t3', as follows:
When an archive program copies a file to backup storage, it sets the archive attribute of the copied files. The file system automatically resets the archive attribute of a directory FCB that has been issued a write command. The archive program can test this attribute in each of the file's directory FCBs via the BDOS Search and Search Next functions. If all directory FCBs have the archive attribute set, it indicates that the file has not been modified since the previous archives. Note that the CP/M 3 PIP utility supports file archival.
Attributes f1' through f4' are available for definition by the user.
The interface attributes are indicated by bits f5' through f8' and cannot be used as file attributes. Interface attributes f5' and f6' can request options for BDOS Make File, Close File, Delete File, and Set File Attributes functions. Table 2-3 defines options indicated by the f5' and f6' interface attribute bits for these functions.
Table 2-3. BDOS Interface Attributes
Section 3 discusses each interface attribute in detail in the definitions of the above functions. Attributes f5' and f6' are always reset when control is returned to the calling program. Interface attributes f7' and f8' are reserved for internal use by the DOS file system.
User Number Conventions
The CP/M 3 User facility divides each drive directory into sixteen logically independent directories, designated as user 0 through user 15. Physically, all user directories share the directory area of a drive. In most other aspects, however, they are independent. For example, files with the same name can exist on different user numbers of the same drive with no conflict. However, a single file cannot reside under more than one user number.
Only one user number is active for a program at one time, and the current user number applies to all drives on the system. Furthermore, the FCB format does not contain any field that can be used to override the current user number. As a result, all file and directory operations reference directories associated with the current user number. However, it is possible for a program to access files on different user numbers; this can be accomplished by setting the user number to the file's user number with the BDOS Set User function before making the desired BDOS function call for the file. Note that this technique must be used carefully. An error occurs if a program attempts to read or write to a file under a user number different from the user number that was active when the file was opened.
When the CCP loads and executes a transient program, it initializes the user number to the value displayed in the system prompt. If the system prompt does not display a user number, user zero is implied. A transient program can change its user number by making a BDOS Set User function call. Changing the user number in this way does not affect the CCP's user number displayed in the system prompt. When the transient program terminates, the CCP's user number is restored. However, an option of the BDOS Program Chain command allows a program to pass its current user number and default drive to the chained program.
User 0 has special properties under CP/M 3. When the current user number is not equal to zero, and if a requested file is not present under the current user number, the file system automatically attempts to open the file under user zero. If the file exists under user zero, and if it has the system attribute, t2', set, the file is opened from user zero. Note, however, that files opened in this way cannot be written to; they are available only for read access. This procedure allows utilities that may include overlays and any other commonly accessed files to be placed on user zero, but also be available for access from other user numbers. As a result, commonly needed utilities need not be copied to all user numbers on a directory, and you can control which user zero files are directly accessible from other user numbers.
Directory Labels and XFCBs
The BDOS file system includes two special types of FCBs: the XFCB and the Directory Label. The XFCB is an extended FCB that optionally can be associated with a file in the directory. If present, it contains the file's password. Note that password protected files and XFCBs are supported only in the banked version of CP/M 3. The format of the XFCB follows.
Figure 2-1. XFCB Format
An XFCB can be created only on a drive that has a directory label, and only if the directory label has activated password protection. For drives in this state, an XFCB can be created for a file in two ways: by the BDOS Make function or by the BDOS Write File XFCB function. The BDOS Make function creates an XFCB if the calling program requests that a password be assigned to the created file. The BDOS Write File XFCB function can be used to assign a password to an existing file. Note that in the directory, an XFCB is identified by a drive byte value, byte 0 in the FCB, equal to 16 + N, where N equals the user number.
For its drive, the directory label specifies if file password support is to be activated, and if date and time stamping for files is to be performed. The format of the Directory Label follows.
Figure 2-2. Directory Label Format
Only one Directory Label can exist in a drive's directory. The Directory Label name and type fields are not used to search for a Directory Label; they can be used to identify a disk. A Directory Label can be created, or its fields can be updated by BDOS function 100, Set Directory Label. This function can also assign a Directory Label a password. The Directory Label password, if assigned, cannot be circumvented, whereas file password protection is an option controlled by the Directory Label. Thus, access to the Directory Label password provides a kind of super-user status on that drive.
The nonbanked version of CP/M 3 does not support file passwords. However, it does provide password protection of directory labels. The CP/M 3 RSX, DIRLBL.RSX, which implements BDOS Function 100 in the nonbanked version of CP/M 3, provides this support.
The BDOS file system has no function to read the Directory Label FCB directly. However, the Directory Label data byte can be read directly with the BDOS Function 101, Return Directory Label. In addition, the BDOS Search functions, with a ? in the FCB drive byte, can be used to find the Directory Label on the default drive. In the directory, the Directory Label is identified by a drive byte value, byte 0 in the FCB, equal to 32, 020H.
Only the banked version of CP/M 3 supports file passwords. In the nonbanked version, all BDOS functions with password related options operate the same way the banked version does when passwords are not enabled.
Files can be assigned passwords in two ways: by the Make File function or by the Write File XFCB function. A file's password can also be changed by the Write File XFCB function if the original password is supplied.
Password protection is provided in one of three modes. Table 2-4 shows the difference in access level allowed to BDOS functions when the password is not supplied.
Table 2-4. Password Protection Modes
If a file is password protected in Read mode, the password must be supplied to open the file. A file protected in Write mode cannot be written to without the password. A file protected in Delete mode allows read and write access, but the user must specify the password to delete the file, rename the file, or to modify the file's attributes. Thus, password protection in mode 1 implies mode 2 and 3 protection, and mode 2 protection implies mode 3 protection. All three modes require the user to specify the password to delete the file, rename the file, or to modify the file's attributes.
If the correct password is supplied, or if password protection is disabled by the Directory Label, then access to the BDOS functions is the same as for a file that is not password protected. In addition, the Search For First and Search For Next functions are not affected by file passwords.
Table 2-5 lists the BDOS functions that test for password.
Table 2-5. BDOS Functions That Test For Password
File passwords are eight bytes in length. They are maintained in the XFCB Directory Label in encrypted form. To make a BDOS function call for a file that requires a password, a program must place the password in the first eight bytes of the current DMA, or specify it with the BDOS function, Set Default Password, prior to making the function call.
Note: the BDOS keeps an assigned default password value until it is replaced with a new assigned value.
File Date and Time Stamps
The CP/M 3 File System uses a special type of directory entry called an SFCB to record date and time stamps for files. When a directory has been initialized for date and time stamping, SFCBs reside in every fourth position of the directory. Each SFCB maintains the date and time stamps for the previous three directory entries as shown in Figure 2-3.
Figure 2-3. Directory Record with SFCB
This figure shows a directory record that contains an SFCB. Directory records consist of four directory entries, each 32 bytes long. SFCBs always occupy the last position of a directory record.
The SFCB directory item contains five fields. The first field is one byte long and contains the value 021H. This value identifies the SFCB in the directory. The next three fields, the SFCB subfields, contain the date and time stamps for their corresponding FCB entries in the directory record. These fields are 10 bytes long. The last byte of the SFCB is reserved for system use. The format of the SFCB subfields is shown in Table 2-6.
Table 2-6. SFCB Subfields Format
An SFCB subfield contains valid information only if its corresponding FCB in the directory record is an extent zero FCB. This FCB is a file's first directory entry. For password protected files, the SFCB subfield also contains the password mode of the file. This field is zero for files that are not password protected. The BDOS Search and Search Next functions can be used to access SFCBs directly. In addition, BDOS Function 102 can return the file date and time stamps and password mode for a specified file. Refer to Section 3, Function 102, for a description of the format of a date and time stamp field.
CP/M 3 supports three types of file stamping: create, access, and update. Create stamps record when the file was created, access stamps record when the file was last opened, and update stamps record the last time the file was modified. Create and access stamps share the same field. As a result, file access stamps overwrite any create stamps.
The CP/M 3 utility, INITDIR, initializes a directory for date and time stamping by placing SFCBs in every fourth directory entry. Date and time stamping is not supported on disks that have not been initialized in this manner. For initialized disks the disks' Directory Label determines the type of date and time stamping supported for files on the drive. If a disk does not have a Directory Label, or if it is Read-Only, or if the disk's Directory Label does not specify date and time stamping, then date and time stamping for files is not performed. Note that the Directory Label is also time stamped, but these stamps are not made in an SFCB. Time stamp fields in the last eight bytes of the Directory Label record when it was created and last updated. Access stamping for Directory Labels is not supported.
The BDOS file system uses the CP/M 3 system date and time when it records a date and time stamp. This value is maintained in a field in the System Control Block (SCB). On CP/M 3 systems that support a hardware clock, the BIOS module directly updates the SCB system date and time field. Otherwise, date and time stamps record the last initialized value for the system date and time. The CP/M 3 DATE utility can be used to set the system date and time.
Record Blocking and Deblocking
Under CP/M 3, the logical record size for disk I/O is 128 bytes. This is the basic unit of data transfer between the operating system and transient programs. However, on disk, the record size is not restricted to 128 bytes. These records, called physical records, can range from 128 bytes to 4K bytes in size. Record blocking and deblocking is required on systems that support drives with physical record sizes larger than 128 bytes.
The process of building up physical records from 128 byte logical records is called record blocking. This process is required in write operations. The reverse process of breaking up physical records into their component 128 byte logical records is called record deblocking. This process is required in read operations. Under CP/M 3, record blocking and deblocking is normally performed by the BDOS.
Record deblocking implies a read-ahead operation. For example, if a transient program makes a BDOS function call to read a logical record that resides at the beginning of a physical record, the entire physical record is read into an internal buffer. Subsequent BDOS read calls for the remaining logical records access the buffer instead of the disk. Conversely, record blocking results in the postponement of physical write operations but only for data write operations. For example, if a transient program makes a BDOS write call, the logical record is placed in a buffer equal in size to the physical record size. The write operation on the physical record buffer is postponed until the buffer is needed in another I/O operation. Note that under CP/M 3, directory write operations are never postponed.
Postponing physical record write operations has implications for some applications programs. For those programs that involve file updating, it is often critical to guarantee that the state of the file on disk parallels the state of the file in memory after the update operation. This is only an issue on systems where physical write operations are postponed because of record blocking and deblocking. If the system should crash while a physical buffer is pending, data would be lost. To prevent this loss of data, the BDOS Flush Buffers function, function 48, can be called to force the write of any pending physical buffers.
Note: the CCP automatically discards all pending physical data buffers when it receives control following a system warm start. However, the BDOS file system automatically makes a Flush Buffers call in the Close File function. Thus, it is sufficient to close a file to ensure that all pending physical buffers for that file are written to the disk.
CP/M 3 can read or write multiple 128-byte records in a single BDOS function call. This process, called multi-sector I/O, is useful primarily in sequential read and write operations, particularly on drives with physical record sizes larger than 128 bytes. In a multi-sector I/O operation, the BDOS file system bypasses, when possible, all intermediate record buffering. Data is transferred directly between the TPA and the drive. In addition, the BDOS informs the BIOS when it is reading or writing multiple physical records in sequence on a drive. The BIOS can use this information to further optimize the I/O operation resulting in even better performance. Thus, the primary objective of multi-sector I/O is to improve sequential I/O performance. The actual improvement obtained, however, depends on the hardware environment of the host system, and the implementation of the BIOS.
The number of records that can be supported with multi-sector I/O ranges from 1 to 128. This value can be set by BDOS function 44, Set multi-sector Count. The multi-sector count is set to one when a transient program begins execution. However, the CP/M 3 LOADER module executes with the multi-sector Count set to 128 unless the available TPA space is less than 16K. In addition, the CP/M 3 PIP utility also sets the multi-sector count to 128 when sufficient buffer space is available. Note that the greatest potential performance increases are obtained when the multi-sector count is set to 128. Of course, this requires a 16K buffer.
The multi-sector count determines the number of operations to be performed by the following BDOS functions:
If the multi-sector count is N, calling one of the above functions is equivalent to making N function calls. If a multi-sector I/O operation is interrupted with an error such as reading unwritten data, the file system returns in register H the number of 128-byte records successfully processed.
Disk Reset and Removable Media
The BDOS functions, Disk Reset (function 13) and Reset Drive (function 37) allow a program to control when a disk's directory is to be reinitialized for file operations. This process of initializing a disk's directory is called logging-in the drive. When CP/M 3 is cold started, all drives are in the reset state. Subsequently, as drives are referenced, they are automatically logged-in by the file system. Once logged-in, a drive remains in the logged-in state until it is reset by BDOS function 13 or 37.
Following the reset operation, the drive is again automatically logged-in by the file system when it is next used. Note that BDOS functions 13 and 37 have similar effects except that function 13 is directed to all drives on the system. Any combination of drives can be reset with Function 37.
Logging-in a drive consists of several steps. The most important step is the initialization of the drive's allocation vector. The allocation vector records the allocation and deallocation of data blocks to files, as files are created, extended, deleted, and truncated, Another function performed during drive log-in is the initialization of the directory check-sum vector. The file system uses the check-sum vector to detect media changes on a drive. Note that permanent drives, which are drives that do not support media changes, might not have check-sum vectors. If directory hashing has been specified for the drive, a BIOS and GENCPM option, the file system creates a hash table for the directory during log-in.
The primary use of the drive reset functions is to prepare for a media change on a drive. Subsequently, when the drive is accessed by a BDOS function call, the drive is automatically logged-in. Resetting a drive has two important side effects. First of all, any pending blocking/deblocking buffers on the reset drive are discarded. Secondly, any data blocks that have been allocated to files that have not been closed are lost. An application program should close files, particularly files that have been written to, prior to resetting a drive.
Although CP/M 3 automatically relogs in removable media when media changes are detected, the application program should still explicitly reset a drive before prompting the user to change disks.
File Byte Counts
Although the logical record size of CP/M 3 is restricted to 128 bytes, CP/M 3 does provide a mechanism to store and retrieve a byte count for a file. This facility can identify the last byte of the last record of a file. The BDOS Compute File Size function returns the random record number, plus 1, of the last record of a file.
The BDOS Set File Attributes function can set a file's byte count. Conversely, the Open function can return a file's byte count to the cr field of the FCB. The BDOS Search and Search Next functions also return a file's byte count. These functions return the byte count in the s1 field of the FCB returned in the current DMA buffer (see BDOS Functions Returned 17 and 26).
Note that the file system does not access or update the byte count value in file read or write operations. However, the BDOS Make File function does set the byte count of a file to zero when it creates a file in the directory.
BDOS Error Handling
The BDOS file system responds to error situations in one of three ways:
The file system handles the majority of errors it detects by method 1. Two examples of this kind of error are the file not found error for the open function and the reading unwritten data error for a read function. More serious errors, such as disk I/O errors, are usually handled by method 2. Errors in this category, called physical and extended errors, can also be reported by methods 1 and 3 under program control.
The BDOS Error Mode, which can exist in three states, determines how the file system handles physical and extended errors. In the default state, the BDOS displays the error message, and terminates the calling program, method 2. In return error mode, the BDOS returns control to the calling program with the error identified in registers A, H, and L, method 1. In return and display mode, the BDOS returns control to the calling program with the error identified in registers A, H, and L, and also displays the error message at the console, method 3. While both return modes protect a program from termination because of a physical or extended error, the return and display mode also allows the calling program to take advantage of the built-in error reporting of the BDOS file system. Physical and extended errors are displayed on the console in the following format:
CP/M Error on d: error message BDOS function = nn File = filename.typ
where d identifies the drive selected when the error condition is detected; error message identifies the error; nn is the BDOS function number, and filename.typ identifies the file specified by the BDOS function. If the BDOS function did not involve an FCB, the file information is omitted. Note that the second line of the above error message is displayed only in the banked version of CP/M 3 if expanded error message reporting is requested in GENCPM. It is not displayed in the nonbanked version of CP/M 3.
The BDOS physical errors are identified by the following error messages:
The Disk I/O error results from an error condition returned to the BDOS from the BIOS module. The file system makes BIOS read and write calls to execute file-related BDOS calls. If the BIOS read or write routine detects an error, it returns an error code to the BDOS resulting in this error.
The Invalid Drive error also results from an error condition returned to the BDOS from the BIOS module. The BDOS makes a BIOS Select Disk call prior to accessing a drive to perform a requested BDOS function. If the BIOS does not support the selected disk, the BDOS returns an error code resulting in this error message.
The Read-Only File error is returned when a program attempts to write to a file that is marked with the Read-Only attribute. It is also returned to a program that attempts to write to a system file opened under user zero from a nonzero user number. In addition, this error is returned when a program attempts to write to a file password protected in Write mode if the program does not supply the correct password.
The Read-Only Disk error is returned when a program writes to a disk that is in read-only status. A drive can be placed in read-only status explicitly with the BDOS Write Protect Disk function.
The BDOS extended errors are identified by the following error messages:
The File Password error is returned when the file password is not supplied, or when it is incorrect. This error is reported only by the banked version of CP/M 3.
The File Exists error is returned by the BDOS Make File and Rename File functions when the BDOS detects a conflict such as a duplicate filename and type.
The ? in Filename error is returned when the BDOS detects a ? in the filename or type field of the passed FCB for the BDOS Rename File, Set File Attributes, Open File, Make File, and Truncate File functions.
The following paragraphs describe the error return code conventions of the BDOS file system functions. Most BDOS file system functions fall into three categories in regard to return codes: they return an Error Code, a Directory Code, or an Error Flag. The error conventions of CP/M 3 are designed to allow programs written for earlier versions of CP/M to run without modification.
The following BDOS functions return an Error Code in register A.
The Error Code definitions for register A are shown in Table 2-7.
Table 2-7. Register A BDOS Error Codes
For BDOS read or write functions, the file system also sets register H when the returned Error Code is a value other than zero or 255. In this case, register H contains the number of 128-byte records successfully read or written before the error was encountered. Note that register H can contain only a nonzero value if the calling program has set the BDOS Multi-Sector Count to a value other than one; otherwise register H is set to zero. On successful functions, Error Code = 0, register H is also set to zero. If the Error Code equals 255, register H contains a physical error code (see Table 2-11).
The following BDOS functions return a Directory Code in register A:
The Directory Code definitions for register A are shown in Table 2-8.
Table 2-8. BDOS Directory Codes
With the exception of the BDOS search functions, all functions in this category return with the directory code set to zero on successful returns. However, for the search functions, a successful Directory Code also identifies the relative starting position of the directory entry in the calling program's current DMA buffer.
If the Set BDOS Error Mode function is used to place the BDOS in return error mode, the following functions return an Error Flag on physical errors:
The Error Flag definition for register A is shown in Table 2-9.
Table 2-9. BDOS Error Flags
The BDOS returns nonzero values in register H to identify a physical or extended error if the BDOS Error Mode is in one of the return modes. Except for functions that return a Directory Code, register A equal to 255 indicates that register H identifies the physical or extended error. For functions that return a Directory Code, if register A equals 255, and register H is not equal to zero, register H identifies the physical or extended error. Table 2-10 shows the physical and extended error codes returned in register H.
Table 2-10. BDOS Physical and Extended Errors Code Meaning
The following two functions represent a special case because they return an address in registers H and L.
When the BDOS is in return error mode, and it detects a physical error for these functions, it returns to the calling program with registers A, H, and L all set to 255. Otherwise, they return no error code.
Page Zero Initialization
Page Zero is the region of memory located from 0000H to 00FFH. This region contains several segments of code and data that are used by transient programs while running under CP/M 3. The code and data areas are shown in Table 2-11 for reference.
Table 2-11. Page Zero Areas
The CCP initializes Page Zero prior to initiating a transient program. The fields at 0050H and above are initialized from the command line invoking the transient program. The command line format was described in detail in Section 1.6.2. To summarize, a command line usually takes the form:
<command> <command tail>
The CCP initializes the command drive field at 0050H to the drive index, A = 1, P = 16, of the drive from which the transient program was loaded.
The default FCB at 005CH is defined if a command tail is entered. Otherwise, the fields at 005CH, 0068H to 006BH are set to binary zeros, the fields from 005DH to 0067H are set to blanks. The fields at 0051H through 0053H are set if a password is specified for the first <file spec> of the command tail. If not, these fields are set to zero.
The default FCB at 006CH is defined if a second <file spec> exists in the command tail. Otherwise, the fields at 006CH, 0078H to 007BH are set to binary zeros, the fields from 005DH to 0067H are set to blanks. The fields at 0054H through 0056H are set if a password is specified for the second <file spec> of the command tail. If not, these fields are set to zero.
Transient programs often use the default FCB at 005CH for file operations. This FCB may even be used for random file access because the three bytes starting at 007DH are available for this purpose. However, a transient program must copy the contents of the default FCB at 006CH to another area before using the default FCB at 005CH, because an open operation for the default FCB at 005CH overwrites the FCB data at 006CH.
The default DMA address for transient programs is 0080H. The CCP also initializes this area to contain the command tall of the command line. The first position contains the number of characters in the command line, followed by the command line characters. The character following the last command tail character is set to binary zero. The command line characters are preceded by a leading blank and are translated to ASCII upper-case. Because the 128-byte region beginning at 0080H is the default DMA, the BDOS file system moves 128-byte records to this area with read operations and accesses 128-byte records from this area with write operations. The transient program must extract the command tail information from this buffer before performing file operations unless it explicitly changes the DMA address with the BDOS Set DMA Address function.
The Page Zero fields of 0051H through 0056H locate the password fields of the first two file specifications in the command tail if they exist. These fields are provided so that transient programs are not required to parse the command tail for password fields. However, the transient program must save the password, or change the DMA address before performing file operations.
The following example illustrates the initialization of the command line fields of Page Zero. Assuming the following command line is typed at the console:
D>A:PROGRAM B:FILE,TYPE ; PASS C:FILE.TYPE ; PASSWORD
A hexadecimal dump of 0050H to 00A5H would show the Page Zero initialization performed by the CCP.
0050H: 01 0D 00 04 9D 00 08 00 00 00 00 00 02 46 49 4C .............FIL 0060H: 45 20 20 20 20 54 59 50 00 00 00 00 03 46 49 4C E TYP.....FIL 0070H: 45 20 20 20 20 54 59 50 00 00 00 00 00 00 00 00 E TYP........ 0080H: 24 20 42 3A 46 49 4C 45 2E 54 59 50 3B 50 41 53 . B:FILE.TYP;PAS 0090H: 53 20 43 3A 46 49 4C 45 2E 54 59 50 3B 50 41 53 S C:FILE.TYP;PAS 00A0H: 53 57 4F 52 44 00 SWORD.
End of Section 2
page URL: www.bigfoot.com/~c128page/cpm3-prg/cpm3prg2.htm