Digital Research : CP/M 3 Programmer’s Manual

Page 1

DIGITALRESEARCH®

CP/M Plus™
(CP/M Version 3)

Operating System
Programmer's Guide
COPYRIGHT
Copyright ©1983 Digital Research Inc. All rights reserved. No part of this publication may be reproduced,
transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, inany form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without
the prior written permission of Digital Research Inc., 60 Garden Court, Box DRI, Monterey, California 93942.
DISCLAIMER
DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO
THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Digital Research Inc.
reserves the right to revise this publication and to make changes from time to time in the content hereof without
any person of such revision or changes.
NOTICE TO USER
From time to time changes are made in the filenames and in the files actually included on the distribution disk.
This manual should not be construed as a representation or warranty that such files or facilities exist on the
distribution disk or as part of the materials and programs distributed. Most distribution disks include a"README.DOC" file. This file explains variations from the manual which do constitute modification of themanual and the items included therewith. Be sure to read this file before using the software.
TRADEMARKS
CP/M and Digital Research and its logo are registered trademarks of Digital Research Inc. ASM, CP/M Plus,
LINK-80, MAC, MP/M, MP/M II, and RMAC are trademarks of Digital Research Inc. Intel is a registeredtrademark of Intel Corporation. The CP/M Plus (CP/M Version 3) Operating System Programmer's Guide wasprinted in the United States of America.
First Edition: January 1983
Second Edition: April 1983

Digital Research : CP/M 3 Programmer’s Manual

Page 2

Table Of Contents
FOREWORDSECTION 1 : INTRODUCTION TO CP/M 3
1.1 BANKED AND NON-BANKED MEMORY ORGANIZATION
1.2 SYSTEM COMPONENTS
1.3 SYSTEM COMPONENT INTERACTION AND COMMUNICATION
1.4 MEMORY REGION BOUNDARIES
1.5 DISK AND DRIVE ORGANIZATION AND REQUIREMENTS
1.6 SYSTEM OPERATION
1.7 SYSTEM CONTROL BLOCKSECTION 2 : THE BDOS SYSTEM INTERFACE
2.1 BDOS CALLING CONVENTIONS
2.2 BDOS SERIAL DEVICE I/O
2.3 BDOS FILE SYSTEM
2.4 PAGE ZERO INITIALIZATIONSECTION 3 : BDOS FUNCTION CALLSBDOS FUNCTION 0: SYSTEM RESETBDOS FUNCTION 1: CONSOLE INPUTBDOS FUNCTION 2: CONSOLE OUTPUTBDOS FUNCTION 3: AUXILIARY INPUTBDOS FUNCTION 4: AUXILIARY OUTPUTBDOS FUNCTION 5: LIST OUTPUTBDOS FUNCTION 6: DIRECT CONSOLE I/0
BDOS FUNCTION 7: AUXILIARY INPUT STATUS
BDOS FUNCTION 8: AUXILIARY OUTPUT STATUS
BDOS FUNCTION 9: PRINT STRING
BDOS FUNCTION 10: READ CONSOLE BUFFER
BDOS FUNCTION 11: GET CONSOLE STATUS
BDOS FUNCTION 12: RETURN VERSION NUMBER
BDOS FUNCTION 13: RESET DISK SYSTEMBDOS FUNCTION 14: SELECT DISKBDOS FUNCTION 15: OPEN FILEBDOS FUNCTION 16: CLOSE FILEBDOS FUNCTION 17: SEARCH FOR FIRSTBDOS FUNCTION 18: SEARCH FOR NEXTBDOS FUNCTION 19: DELETE FILEBDOS FUNCTION 20: READ SEQUENTIALBDOS FUNCTION 21: WRITE SEQUENTIALBDOS FUNCTION 22: MAKE FILEBDOS FUNCTION 23: RENAME FILEBDOS FUNCTION 24: RETURN LOGIN VECTORBDOS FUNCTION 25: RETURN CURRENT DISKBDOS FUNCTION 26: SET DMA ADDRESSBDOS FUNCTION 27: GET ADDR(ALLOC)BDOS FUNCTION 28: WRITE PROTECT DISKBDOS FUNCTION 29: GET READ-ONLY VECTORBDOS FUNCTION 30: SET FILE ATTRIBUTESBDOS FUNCTION 31: GET ADDR(DPB PARMS)
BDOS FUNCTION 32: SET/GET USER CODEBDOS FUNCTION 33: READ RANDOMBDOS FUNCTION 34: WRITE RANDOMBDOS FUNCTION 35: COMPUTE FILE SIZEBDOS FUNCTION 36: SET RANDOM RECORDBDOS FUNCTION 37: RESET DRIVE
BDOS FUNCTION 38: ACCESS DRIVE
BDOS FUNCTION 39: FREE DRIVE

5
6
6
8
9
11
12
13
21
23
23
23
26
43
47
47
47
48
48
48
49
49
50
50
50
51
53
53
54
54
55
56
57
58
59
60
61
62
64
64
65
65
66
66
67
67
68
69
69
70
72
73
74
74
74

Digital Research : CP/M 3 Programmer’s Manual
BDOS FUNCTION 40: WRITE RANDOM WITH ZERO FILLBDOS FUNCTION 41: TEST AND WRITE RECORDBDOS FUNCTION 42: LOCK RECORDBDOS FUNCTION 43: UNLOCK RECORDBDOS FUNCTION 44: SET MULTI-SECTOR COUNTBDOS FUNCTION 45: SET BDOS ERROR MODE
BDOS FUNCTION 46: GET DISK FREE SPACEBDOS FUNCTION 47: CHAIN TO PROGRAMBDOS FUNCTION 48: FLUSH BUFFERSBDOS FUNCTION 49: GET / SET SYSTEM CONTROLBLOCKBDOS FUNCTION 50: DIRECT BIOS CALLSBDOS FUNCTION 59: LOAD OVERLAYBDOS FUNCTION 60: CALL RESIDENT SYSTEM EXTENSIONBDOS FUNCTION 98: FREE BLOCKSBDOS FUNCTION 99: TRUNCATE FILEBDOS FUNCTION 100: SET DIRECTORY LABELBDOS FUNCTION 101: RETURN DIRECTORY LABEL DATABDOS FUNCTION 102: READ FILE DATE STAMPS AND PASSWORD MODE
BDOS FUNCTION 103: WRITE FILE XFCBBDOS FUNCTION 104: SET DATE AND TIMEBDOS FUNCTION 105: GET DATE AND TIMEBDOS FUNCTION 106: SET DEFAULT PASSWORDBDOS FUNCTION 107: RETURN SERIAL NUMBER
BDOS FUNCTION 108: GET/SET PROGRAM RETURN CODEBDOS FUNCTION 109: GET/SET CONSOLE MODE
BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER
BDOS FUNCTION 111: PRINT BLOCKBDOS FUNCTION 112: LIST BLOCKBDOS FUNCTION 152: PARSE FILENAME
SECTION 4 : PROGRAMMING EXAMPLES
4.1 A SAMPLE FILE-TO -FILE COPY PROGRAM
4.2 A SAMPLE FILE DUMP UTILITY
4.3 A SAMPLE RANDOM ACCESS PROGRAM
4.4 CONSTRUCTION OF AN RSX PROGRAM
APPENDIX A : SYSTEM CONTROL BLOCKAPPENDIX B : PRL FILE GENERATION
B. 1 PRL FORMAT
B.2 GENERATING A PRL
APPENDIX C : SPR GENERATIONAPPENDIX D : ASCII AND HEXADECIMAL CONVERSIONSAPPENDIX E : BDOS FUNCTION SUMMARY

Page 3
75
75
75
76
76
77
77
78
78
79
81
82
83
83
84
85
86
87
88
89
89
90
90
91
91
92
93
93
94
97
97
99
102
107
111
115
115
115
116
117
121

List of Tables
TABLE 1-1. CP/M 3 BUILT-IN COMMANDS ...................................................................................................................................................... 16
TABLE 2-1. VALID FILENAME DELIMITERS ......................................................................................................................................................... 28
TABLE 2-2. LOGICAL DRIVE CAPACITY .............................................................................................................................................................. 29
TABLE 2-3. BDOS INTERFACE ATTRIBUTES ....................................................................................................................................................... 32
TABLE 2-4. PASSWORD PROTECTION MODES .................................................................................................................................................... 35
TABLE 2-5. BDOS FUNCTIONS THAT TEST FOR PASSWORD ................................................................................................................................. 36
TABLE 2-6. SFCB SUBFIELDS FORMAT ............................................................................................................................................................. 37
TABLE 2-7. REGISTER A BDOS ERROR CODES ................................................................................................................................................... 41
TABLE 2-8. BDOS DIRECTORY CODES ............................................................................................................................................................. 42
TABLE 2-9. BDOS ERROR FLAGS .................................................................................................................................................................... 42
TABLE 2-10. BDOS PHYSICAL AND EXTENDED ERRORS ....................................................................................................................................... 43
TABLE 2-11. PAGE ZERO AREAS ..................................................................................................................................................................... 43
TABLE 3-1. FUNCTION 6 ENTRY PARAMETERS ................................................................................................................................................... 49

Digital Research : CP/M 3 Programmer’s Manual

Page 4

TABLE 3-2. EDIT CONTROL CHARACTERS (NON-BANKED CP/M 3)........................................................................................................................ 52
TABLE 3-3. EDIT CONTROL CHARACTERS (BANKED CP/M 3) ............................................................................................................................... 52
TABLE 3-4. SYSTEM CONTROL BLOCK .............................................................................................................................................................. 80
TABLE 3-5. PROGRAM RETURN CODES ............................................................................................................................................................ 91
TABLE 3-6. FCB FORMAT.............................................................................................................................................................................. 95
TABLE A-1. SCB FIELDS AND DEFINITIONS ...................................................................................................................................................... 111
TABLE B-1. PRL FILE FORMAT...................................................................................................................................................................... 115
TABLE D-1. ASCII SYMBOLS ........................................................................................................................................................................ 117
TABLE D-2 : ASCII CONVERSION TABLE ......................................................................................................................................................... 117
TABLE E-1. BDOS FUNCTION SUMMARY ....................................................................................................................................................... 121

List of Figures
FIGURE 1-1. NON-BANKED SYSTEM M EMORY ORGANIZATION ..................................................................................6
FIGURE 1-2. BANKED SYSTEM M EMORY ORGANIZATION .........................................................................................7
FIGURE 1-3. BANKED M EMORY WITH BANK 1 IN CONTEXT ......................................................................................7
FIGURE 1-4 : CP/M 3 LOGICAL M EMORY ORGANIZATION .......................................................................................8
FIGURE 1-5. SYSTEM COMPONENTS AND R EGIONS IN LOGICAL MEMORY ...................................................................8
FIGURE 1-6. SYSTEM MODULES AND R EGIONS IN LOGICAL M EMORY ...................................................................... 11
FIGURE 1-7. DISK ORGANIZATION .................................................................................................................... 12
FIGURE 1-8. RSX FILE FORMAT ....................................................................................................................... 20
FIGURE 2-1. EXTENDED FCB FORMAT .............................................................................................................. 34
FIGURE 2-2 : DIRECTORY LABEL FORMAT .......................................................................................................... 34
FIGURE 2-3 SFCB FORMAT ............................................................................................................................ 36

Digital Research : CP/M 3 Programmer’s Manual

Page 5

Foreword
CP/M 3 is a microcomputer operating system designed for the Intel 8080, Intel 8085, or other compatible
microprocessor. To run CP/M 3, your computer must have an ASCII console, which includes a keyboard andscreen, or another display device, from one to sixteen disk drives and a minimum of 32K of memory space. To
support additional memory beyond the 64K addressing limit of the processors listed above, CP/M 3 can also
support bank-switched memory. The minimum memory requirement for a banked system is 96K.
This manual describes the programming environment of CP/M 3, and is written for experienced programmers
who are writing application software in the CP/M 3 environment. It assumes you are familiar with the system
features and utilities described in the CP/M Plus (CP/M Version 3) Operating System User's Guide and theProgrammer's Utilities Guide for the CP/M Family of Operating Systems. It also assumes that your CP/M 3
system has been customized for your computer's hardware and is executing as described in the CP/M Plus
(CP/M Version 3) Operating System User's Guide. If you need to customize your system, please refer to the
CP/M Plus (CP/M Version 3) Operating System System Guide.
Section 1 of this manual describes the components of the operating system, where they reside in memory, andhow they work together to provide a standard operating environment for application programs. Section 2
describes how an application program can call on CP/M 3 to perform serial input and output and manage disk
files. Section 3 provides a detailed description of each operating system function. Section 4 presents example
programs.
The CP/M Plus (CP/M Version 3) Operating System Programmer's Guide contains five appendixes. Appendix
A describes the CP/M 3 System Control Block, and defines its fields. Appendix B supplies the format for the
Page Relocatable Program. Appendix C tells you how to generate System Page Relocatable files. Appendix D
lists the ASCII Symbol Table, and Appendix E summarizes BDOS functions.

Digital Research : CP/M 3 Programmer’s Manual

Page 6

Section 1 : Introduction to CP/M 3This section introduces you to the general features of CP/M 3 with an emphasis on how CP/M 3 organizes yourcomputer's memory. The section begins by describing the general memory organization of banked and nonbanked systems and defines the programming environment they have in common. It then shows how CP/M 3
defines memory space into standard regions for operating system modules and executing programs. Subsequentparagraphs describe the components of the operating system, how they communicate with each other and theapplication program, and in greater detail where each component and program is located in memory. After abrief introduction to disk organization, the final section gives examples of system operation.
CP/M 3 is available in two versions: a version that supports bank-switched memory, and a version that runs on
non-banked systems. CP/M 3 uses the additional memory available in banked systems to provide functions thatare not present in the non-banked version. For example, the banked version of CP/M 3 supports file passwords;
the non-banked version does not. However, because a non-banked system treats passwords the same way as abanked system does when password protection is not enabled, an application program can run under either
system without modification.

1.1 Banked and Non-banked Memory Organization
The memory organization for a non-banked CP/M 3 system is very simple, as shown in Figure 1-1.

Figure 1-1. Non-banked System Memory Organization
In the non-banked organization, physical memory consists of a single, contiguous region addressable from
0000H up to a maximum of 0FFFFH (64K-1). The shaded region below the operating system represents thememory space available for the loading and execution of transient programs. The clear area above the operating
system represents space that GENCPM can allocate to the operating system for disk record buffers anddirectory hash tables, as described in the CP/M Plus (CP/M Version 3) Operating System System Guide. The
minimum size of this area is determined by the specific hardware requirements of the host microcomputer
system.
To expand memory capacity beyond the 64K address space of an 8-bit microprocessor, CP/M 3 supports bankswitched memory in a special version called the banked system. In the banked version, the operating system isdivided into two modules: the resident portion and the banked portion. The resident portion resides in common
memory; the banked portion resides just below the top of banked memory in Bank 0.

Digital Research : CP/M 3 Programmer’s Manual

Page 7

Figure 1-2 shows memory organization under the banked system.

Figure 1-2. Banked System Memory Organization
In Figure 1-2, Bank 0 is switched in or in context. The top region of memory, the common region, is always incontext; that is, it can always be referenced, no matter what bank is switched in. Figure 1-3 shows memoryorganization when Bank 1 is in context.

Figure 1-3. Banked Memory with Bank 1 in Context
From a transient programs perspective, Bank 1 is always in context. The operating system can switch to Bank 0
or other banks when performing operating system functions without affecting the execution of the transient
program. Any bank-switching performed by the operating system is completely transparent to the calling
program. Because the major portion of the operating system resides in Bank 0 in banked systems, morememory space is available for transient programs in banked CP/M 3 systems than in non-banked systems.
The operating system uses the clear areas in Figures 1-2 and 1-3 for disk record buffers and directory hashtables. The clear area in the common region above the operating system represents space that can be allocatedfor data buffers by GENCPM.

Digital Research : CP/M 3 Programmer’s Manual

Page 8Again, the minimum size of this area is determined by the specific hardware requirements of the hostmicrocomputer system.
The banked version of CP/M 3 requires a minimum of two banks, Bank 0 and Bank 1, and can support up to 16
banks of memory. Bank numbers are generally arbitrary with the following exceptions: Bank 0 is the systembank and is in context when CP/M 3 is started. Bank 1 is the transient program bank, and must be contiguousfrom location zero to the top of banked memory. This requirement does not apply to the other banks. However,common memory must be contiguous.
The size of the common region is typically 16K. The only size requirement on the common region is that it
must be large enough to contain the resident portion of the operating system. The maximum top of memory
address for both banked and nonbanked systems is 64K-1 (0FFFFH).
In summary, no matter how physical memory is configured, or whether the operating system is banked or nonbanked, CP/M 3 always organizes memory logically so that to a transient program in any CP/M 3 system,
memory appears as shown in Figure 1-4.

Figure 1-4 : CP/M 3 Logical Memory Organization

1.2 System Components
Functionally, the CP/M 3 operating system is composed of distinct modules. Transient programs cancommunicate with these modules to request system services. Figure 1-5 shows the regions where these modules
reside in logical memory. Note that from the transient program's perspective, Figure 1-5 is just a more detailed
version of Figure 1-4.

Figure 1-5. System Components and Regions in Logical Memory

Digital Research : CP/M 3 Programmer’s Manual

Page 9The Basic Input/Output System, BIOS, is a hardware-dependent module that defines the low-level interface to aparticular computer system. It contains the device-driving routines necessary for peripheral device I/O.
The Basic Disk Operating System, BDOS, is the hardware-independent module that is the logical nucleus of
CP/M 3. It provides a standard operating environment for transient programs by making services available
through numbered system function calls.
The LOADER module handles program loading for the Console Command Processor and transient programs.
Usually, this module is not resident when transient programs execute. However, when it is resident, transient
programs can access this module by making BDOS Function 59 calls.
Resident System Extensions, RSXS, are temporary additional operating system modules that can selectively
extend or modify normal operating system functions. The LOADER module is always resident when RSXs areactive.
The Transient Program Area, TPA, is the region of memory where transient programs execute. The CCP also
executes in this region. The Console Command Processor, CCP, is not an operating system module, but is asystem program that presents a human-oriented interface to CP/M 3 for the user.
The Page Zero region is not an operating system module either, but functions primarily as an interface to the
BDOS module from the CCP and transient programs.
It also contains critical system parameters.

1.3 System Component Interaction and Communication
This section describes interaction and communication between the modules and regions defined in Section 1.2.
The most significant channels of communication are between the BDOS and the BIOS, transient programs andthe BDOS, and transient programs and RSXS.
The division of responsibility between the different modules and the way they communicate with one anotherprovide three important benefits. First, because the operating system is divided into two modules-one that isconfigured for different hardware environments, and one that remains constant on every computer -CP/M 3
software is hardware independent; you can port your programs unchanged to different hardware configurations.
Second, because all communication between transient programs and the BDOS is channeled through Page Zero,
CP/M 3 transient programs execute, if sufficient memory is available, independent of configured memory size.
Third, the CP/M 3 RSX facility can customize the services of CP/M 3 on a selective basis.

1.3.1 The BDOS and BIOS
CP/M 3 achieves hardware independence through the interface between the BDOS and the BIOS modules ofthe operating system. This interface consists of a series of entry points in the BIOS that the BDOS calls toperform hardware-dependent primitive functions such as peripheral device VO. For example, the BDOS calls
the CONIN entry point of the BIOS to read the next console input character.
A system implementor can customize the BIOS to match a specific hardware environment. However, evenwhen the BIOS primitives are customized to match the host computer's hardware environment, the BIOS entry
points and the BDOS remain constant. Therefore, the BDOS and the BIOS modules work together to give the
CCP and other transient programs hardware-independent access to CP/M 3's facilities.

1.3.2 Applications and the BDOS

Digital Research : CP/M 3 Programmer’s Manual

Page 10

Transient programs and the CCP access CP/M 3 facilities by making BDOS function calls. BDOS functions cancreate, delete, open, and close disk files, read or write to opened files, retrieve input from the console, send
output to the console or list device, and perform a wide range of other services described in Section 3,"BDOS
Functions."
To make a BDOS function call, a transient program loads CPU registers with specific entry parameters andcalls location 0005H in Page Zero. If RSXs are not active in memory, location 0005H contains a jump
instruction to location BDOS_base + 6. If RSXs are active, location 0005H contains a jump instruction to an
address below BDOS -base. Thus, the Page Zero interface allows programs to run without regard to where theoperating system modules are located in memory. In addition, transient programs can use the address at location
0006H as a memory ceiling.
Some BDOS functions are similar to BIOS entry points, particularly in the case of simple device I/O. For
example, when a transient program makes a console output BDOS function call, the BDOS makes a BIOS
console output call. In the case of disk I/O, however, this relationship is more complex. The BDOS might callmany BIOS entry points to perform a single BDOS file I/O function.
Transient programs can terminate execution by jumping to location 0000H in the Page Zero region. Thislocation contains a jump instruction to BIOS base+3, which contains a jump instruction to the BIOS warm startroutine. The BIOS warm start routine loads the CCP into memory at location 100H and then passes control toit.
The Console Command Processor is a special system program that executes in the TPA and makes BDOS calls
just like an application program. However, the CCP has a unique role: it gives the user access to operating
system facilities while transient programs are not executing. It includes several built-in commands, such as
TYPE and DIR, that can be executed directly without having to be loaded from disk. When the CCP receives
control, it reads the user's command lines, distinguishes between built-in and transient commands, and whennecessary, calls upon the LOADER module to load transient programs from disk into the TPA for execution.
Section 1.6.2 describes CCP operation in detail.

1.3.3 Applications and RSXs
A Resident System Extension is a temporary additional operating system module. An RSX can extend or
modify one or more operating system functions selectively. As with a standard BDOS function, a transient
program accesses an RSX function through a numbered function call.
At any one time there might be zero, one, or multiple RSXs active in memory. When a transient program makes
a BDOS function call, and RSXs are active, each RSX examines the function number of the call. If the function
number matches the function the RSX is designed to extend or modify, the RSX performs the requested
function. Otherwise, the RSX passes the function request to the next RSX. Non-intercepted functions are
eventually passed to the BDOS for standard execution.
RSXs are loaded into memory when programs containing RSXs are loaded. The CP/M 3 utility, GENCOM, canattach RSXs to program files. When attaching RSXS, GENCOM places a special one page header at the
beginning of the program file. The CCP reads this header, learns that a program has attached RSXS, and loads
the RSXs accordingly. The header itself is not loaded into memory; it merely indicates to the CCP that RSX
loading is required.
The LOADER module is a special type of RSX that supports BDOS function 59, Load Overlay. It is always
resident when RSXs are active. To indicate RSX support is required, a program that calls function 59 must have
an RSX header attached by GENCOM, even if the program does not require other RSXS. When the CCP
encounters this type of header in a program file when no RSXs are active, it sets the address at location 0006H
in Page Zero to LOADER-base + 6 instead of BDOS_base + 6.

Digital Research : CP/M 3 Programmer’s Manual

Page 11

1.4 Memory Region Boundaries
This section reviews memory regions under CP/M 3, and then describes some details of region boundaries. It
then relates the sizes of various modules to the space available for the execution of transient programs. Figure
1-6 reviews the location of regions in logical memory.

Figure 1-6. System Modules and Regions in Logical Memory
First note that all memory regions in CP/M 3 are page-aligned. This means that regions and operating systemmodules must begin on a page boundary. A page is defined as 256 bytes, so a page boundary always begins at
an address where the low-order byte is zero.
The term High Memory in Figure 1-6 denotes the high address of a CP/M 3 system. This address may fall
below the actual top of memory address if space above the operating system has been allocated for directoryhashing or data buffering by GENCPM. The maximum top of memory address for both banked and non-banked
systems is 64K-1 (0FFFFH).
The labels BIOS-base, BDOS_base, and LOADER_base represent the base addresses of the operating system
regions. These addresses always fall on page boundaries. The size of the BIOS region is not fixed, but isdetermined by the requirements of the host computer system.
The size of the BDOS region differs for the banked and non-banked versions of CP/M 3. In the banked version,
the resident BDOS size is 6 pages, 1.5K. In the non-banked system, the BDOS size ranges from 31 pages,
7.75K, to 33 pages, 8.25K, depending on system generation options and BIOS requirements.
RSXs are page aligned modules that are stacked in memory below LOADER_base in memory. In theconfiguration shown in Figure 1-6, location 0005H of Page Zero contains a jump to location RSX(N)_base + 6.
Thus, the memory ceiling of the TPA region is reduced when RSXs are active.
Under CP/M 3. the CCP is a transient program that the BIOS loads into the TPA region of memory at system
cold and warm start. The BIOS also loads the LOADER module at this time, because the LOADER module isattached to the CCP. When the CCP gains control, it relocates the LOADER module just below BDOS_base.
The LOADER module handles program loading for the CCP. It is three pages long.

Digital Research : CP/M 3 Programmer’s Manual

Page 12The maximum size of a transient program that can be loaded into the TPA Is limited by LOADER-base because
the LOADER cannot load a program over itself. Transient programs may extend beyond this point, however, byusing memory above LOADER_base for uninitialized data areas such as I/O buffers. Programs that use
memory above BDOS-base cannot make BDOS function calls.

1.5 Disk and Drive Organization and Requirements
CP/M 3 can support up to sixteen logical drives, identified by the letters A through PI, with up to 512
megabytes of storage each. A logical drive usually corresponds to a physical drive on the system, particularly
for physical drives that support removable media such as floppy disks. High-capacity hard disks, however, arecommonly divided up into multiple logical drives. Figure 1-7 illustrates the standard organization of a CP/M 3
disk.

Figure 1-7. Disk Organization
In Figure 1-7, the first N tracks are the system tracks. System tracks are required only on the disk used by CP/M
3 during system cold start or warm start. The contents of this region are described in Section 1.6.1. All normal
CP/M 3 disk access is directed to the data tracks which CP/M 3 uses for file storage.
The data tracks are divided into two regions: a directory area and a data area. The directory area defines thefiles that exist on the drive and identifies the data space that belongs to each file. The data area contains the filedata defined by the directory.
If the drive has adequate storage, a CP/M 3 file can be as large as 32 megabytes. The directory area issubdivided into sixteen logically independent directories. These directories are identified by user numbers 0
through 15. During system operation, CP/M 3 runs with the user number set to a single value. The user number
can be changed at the console with the USER command. A transient program can change the user number bycalling a BDOS function.
The user number specifies the currently active directories for all the drives on the system. For example, a PIP
command to copy a file from one disk to another gives the destination file the same user number as the source
file unless the PIP command is modified by the [G] option.
The directory identifies each file with an eight-character filename and a three-character filetype. Together, thesefields must be unique for each file. Files with the same filename and filetype can reside in different user
directories on the same drive without conflict. Under the banked version of CP/M 3, a file can be assigned aneight-character password to protect the file from unauthorized access.
All BDOS functions that involve file operations specify the requested file by filename and filetype. Multiple
files can be specified by a technique called ambiguous reference, which uses question marks and asterisks as

Digital Research : CP/M 3 Programmer’s Manual

Page 13wildcard characters to give CP/M 3 a pattern to match as it searches the directory. A question mark in an
ambiguous reference matches any value in the same position in the directory filename or filetype field. An
asterisk fills the remainder of the filename or filetype field of the ambiguous reference with question marks.
Thus, a filename and filetype field of all question marks, ????????.???, equals an ambiguous reference of two
asterisks, and matches all files in the directory that belong to the current user number.
The CP/M 3 file system automatically allocates directory space and data area space when a file is created or
extended, and returns previously allocated space to free space when a file is deleted or truncated. If no directoryor data space is available for a requested operation, the BDOS returns an error to the calling program. In
general, the allocation and de-allocation of disk space is transparent to the calling program.
As a result, you need not be concerned with directory and drive organization when using the file systemfacilities of CP/M 3.

1.6 System Operation
This section introduces the general operation of CP/M 3. This overview covers topics concerning the CP/M 3
system components, how they function and how they interact when CP/M 3 is running. This section does notdescribe the total functionality of CP/M 3, but simply introduces basic CP/M 3 operations.
For the purpose of this overview, CP/M 3 system operation is divided into five categories. First is system cold
start, the process that begins execution of the operating system. This procedure ends when the Console
Command Processor, CCP, is loaded into memory and the system prompt is displayed on the screen. Second is
the operation of the CCP, which provides the user interface to CP/M 3. Third is transient program initiation,
execution and termination. Fourth is the way Resident System Extensions run under CP/M 3. The fifth and final
category describes the operation of the CP/M 3 SUBMIT utility.

1.6.1 Cold Start Operation
The cold start procedure is typically executed immediately after the computer is turned on. The cold start brings
CP/M 3 into memory and gives it control of the computer's resources. Cold start is a four-stage procedure.
In the first stage, a hardware feature, or ROM-based software associated with system reset, loads a small
program, called the Cold Boot Loader, into memory from the system tracks of drive A (see figure 1 -6). The
Cold Boot Loader is usually 128 or 256 bytes long.
The Cold Boot Loader performs the second stage of the cold start process. It loads the CP/M 3 loader program,
CPMLDR, into memory from the system tracks of the system disk and passes control to it. During this stage,
the Cold Boot Loader can also perform other tasks, such as initializing hardware dependent I/O ports.
CPMLDR performs the third stage in the cold start process. First, it reads the CPM3.SYS file from the data areaof the disk. The CPM3.SYS file, which is created by the CP/M 3 system generation utility GENCPM, contains
the BDOS and BIOS system components and information indicating where these modules are to reside inmemory. Once CPMLDR has loaded the BDOS and BIOS into memory, it sends a sign-on message to theconsole and passes control to the BIOS Cold Boot entry point.
If specified as a GENCPM option, CPMLDR can also display a memory map of the CP/M 3 system.
CPMLDR is a small, self-contained version of CP/M 3 that supports only console output and sequential file
input. Consistent with CP/M 3's organization, it contains two modules, an invariant CPMLDR-BDOS, and avariant CPMLDR -BIOS that is adapted to match the host microcomputer hardware environment. Cold start
initialization of VO ports and similar functions can also be performed in the CPMLDR-BIOS module during
the third stage of cold start.

Digital Research : CP/M 3 Programmer’s Manual

Page 14

In the banked version of CP/M 3, these first three stages of the cold boot procedure are performed with Bank 0
in context. The BIOS Cold Start function switches in Bank 1 before proceeding to stage four.
The fourth and final stage in the cold start procedure is performed by the BIOS Cold Start function, Function 0.
The entry point to this function is located at BIOS -base as described in Section 1.4. The BIOS Cold Startfunction begins by performing any remaining hardware initialization, and initializing Page Zero. To initialize
Page Zero, the BIOS Cold Start function places a jump to BIOS base + 3, the BIOS Warm Start entry point, at
location 0000H, and a jump to BDOS-base + 6, the BDOS entry point, at location 0005H in memory.
The BIOS Cold Start function completes the fourth stage by loading the CCP into the TPA region of memory
and passing control to it. The CCP can be loaded from one of two locations. If there is sufficient space in thesystem tracks for the CCP, it is usually loaded from there. If there is not enough space in the system tracks, theBIOS Cold Start function can read the CCP from the file CCP.COM.
On some banked systems, the CCP is also copied to an alternate bank, so that warm start operations can copy
the CCP into the TPA from memory. This speeds up the system warm start operation, and makes it possible towarm start the system without having to access a system disk.
When the CCP gains control, it displays a prompt that references the default disk. If a PROFILE.SUB submit
file is present on the default drive, the CCP executes this submit file before prompting the user for a command.
At this point, the cold start procedure is complete. Note that the user number is set to zero when CP/M 3 is cold
started. However, the PROFILE submit file can set the user number to another value if this is desirable.
The cold start procedure is designed so that the system tracks need to be initialized only once. This isaccomplished because the system track routines are independent of the configured memory size of the CP/M 3
system. The Cold Boot Loader loads CPMLDR into a constant location in memory. This location is chosenwhen the system is configured. However, CPMLDR locates the BDOS and BIOS system components inmemory as specified by the CPM3.SYS file. The CCP always executes at location 100H in the TPA. Thus,
CP/M 3 allows the user to generate a new system with GENCPM, and then run it without having to update thesystem tracks of the system disk.

1.6.2 CCP Operation
The Console Command Processor provides the user access to CP/M 3 facilities when transient programs are notrunning. It also reads the user's command lines, differentiates between built-in commands and transientcommands, and executes the commands accordingly.
This section describes the responsibilities and capabilities of the CCP in some detail. The section begins with adescription of the CCP's activities when it first receives control from the Cold Start procedure. The section
continues with a general discussion of built-in commands, and concludes with a step-by-step description of theprocedure the CCP follows to execute the user's commands.
When the CCP gains control following a cold start procedure, it displays the system prompt at the console. Thissignifies that the CCP is ready to execute a command. The system prompt displays the letter of the drive
designated as the initial default drive during GENCPM operation. For example, if drive A was specified as theinitial default drive, the CCP displays the following prompt:
A>
After displaying the system prompt, the CCP scans the directory of the default drive for the file PROFILE.SUB.
If the file exists, the CCP creates the command line SUBMIT PROFILE; otherwise the CCP reads the user's
first command line by making a BDOS Read Console Buffer function call (BDOS Function 10).

Digital Research : CP/M 3 Programmer’s Manual

Page 15

The CCP accepts two different command forms. The simplest CCP command form changes the default drive.
The following example illustrates a user changing the default drive from A to B.
A>B:
B>
This command is one of the CCP's built-in commands. Built-in commands are part of the CCP. They reside inmemory while the CCP is active, and therefore can be executed without referencing a disk.
The second command form the CCP accepts is the standard CP/M command line.
A standard CP/M command line consists of a command keyword followed by an optional command tail. The
command keyword and the command tall can be typed in any combination of upper-case and lower-case letters;
the CCP converts all letters in the command line to upper-case. The following syntax defines the standard
CP/M command line:<command> <command tail>where→ <filespec> or <built-in><command tail> → (no command tail) or <filespec> or <filespec><delimiter><filespec><filespec> → {d:}filename{.typ}{;password}<built-in> → one of the CCP built-in commands<delimiter> → one or more blanks or a tab or one of the following:<command>"=,[]<> "→ CP/M 3 drive specification,"A" through "P"filename → 1 to 8 character filename
typ → 1 to 3 character filetypepassword → 1 to 8 character password valued:Fields enclosed in curly brackets are optional. If there is no drive {d:} present in a file specification <filespec>,
the default drive is assumed. If the type field {.typ} is omitted, a type field of all blanks is implied. Omitting the
password field @;password implies a password of all blanks. When a command line is entered at the console, it
is terminated by a return or line-feed keystroke.
Transient programs that run under CP/M 3 are not restricted to the above command tail definition. However,
the CCP only parses command tails in this format for transient programs. Transient programs that define theircommand tails differently must perform their own command tall parsing.
The command field must identify either a built-in command, a transient program, or a submit file. For example,
USER is the keyword that identifies the built-in command that changes the current user number. The CP/M 3
CCP displays the user number in the system prompt when the user number is non-zero. The following example
illustrates changing the user number from zero to 15.

Digital Research : CP/M 3 Programmer’s Manual

Page 16

B>USER 15
15B>
The following table summarizes the built-in commands.
Table 1-1. CP/M 3 Built-in Commands
Command
Meaning
displays a list of all filenames from a disk directory except those marked with the SYS attribute.
DIR
DIRSYS displays a filename list of those files marked with the SYS attribute in the directory.
ERASE erases a filename from a disk directory and releases the storage occupied by the file.
RENAME renames a file.
TYPE displays the contents of an ASCII character file at your console output device.
USER changes from one user number to another.
Some built-in commands have associated command files which expand upon the options provided by the builtin command. If the CCP reads a command line and discovers the built-in command does not support the options
requested in the command line,, the CCP loads the built-in function's corresponding command file to performthe command. The DIR command is an example of this type of command.
Simple DIR commands are supported by the DIR built-in directly. More complex requests are handled by the
DIR.COM utility.
All command keywords that do not identify built-in commands identify either a transient program file or asubmit file. If the CCP identifies a command keyword as a transient program, the transient program file isloaded into the TPA from disk and executed. If it recognizes a submit file, the CCP reconstructs the commandline into the following form:
SUBMIT <command> <command tail>and attempts to load and execute the SUBMIT utility. Thus, the original command field becomes the firstcommand tail field of the SUBMIT command. Section 1.6.5 describes the execution of CP/M 3's SUBMIT
utility. The procedure the CCP follows to parse a standard command line and execute built-in and transientcommands is described as follows:
1. The CCP parses the command line to pick up the command field.
2. If the command field is not preceded by a drive specification, or followed by a filetype or password field, the
CCP checks to see if the command is a CCP built-in function. If the command is a built-in command, and the
CCP can support the options specified in the command tail, the CCP executes the command. Otherwise, the
CCP goes on to step 3.
3. At this point the CCP assumes the command field references a command file or submit file on disk. If theoptional filetype field is omitted from the command, the CCP usually assumes the command field references afile of type COM. For example, if the command field is PIP, the CCP attempts to open the file PIP.COM.
Optionally, the CP/M 3 utility SETDEF can specify that a filetype of SUB also be considered when thecommand filetype field is omitted. When this automatic submit option is in effect, the CCP attempts to open thecommand with a filetype of COM. If the COM file cannot be found, the CCP repeats the open operation with afiletype of SUB. As an alternative, the order of open operations can be reversed so that the CCP attempts toopen with a filetype of SUB first. In either case, the file that is found on disk first determines the filetype fieldthat is ultimately associated with the command.

Digital Research : CP/M 3 Programmer’s Manual

Page 17

If the filetype field is present in the command, it must equal COM, SUB or PRL. A PRL file is a Page
Relocatable file used in Digital Research's multiuser operating system, MP/M. Under CP/M 3, the CCP handles
PRL files exactly like COM files.
If the command field is preceded by a drive specification id:), the CCP attempts to open the command or submit
file on the specified drive. Otherwise, the CCP attempts to open the file on the drives specified in the drive
chain.
The drive chain specifies up to four drives that are to be referenced in sequence for CCP open operations ofcommand and submit files. If an open operation is unsuccessful on a drive in the drive chain because the filecannot be found, the CCP repeats the open operation on the next drive in the chain. This sequence of open
operations is repeated until the file is found, or the drive chain is exhausted. The drive chain contains thecurrent default drive as its only drive unless the user modifies the drive chain with the CP/M 3 SETDEF utility.
When the current user number is non-zero, all open requests that fail because the file cannot be found, attempt
to locate the command file under user zero. If the file exists under user zero with the system attribute set, thefile is opened from user zero. This search for a file under user zero is made by the BDOS Open File function.
Thus, the user zero open attempt is made before advancing to the next drive in the search chain.
When automatic submit is in effect, the CCP attempts to open with the first filetype, SUB or COM, on all
drives in the search chain before trying the second filetype.
In the banked system, if a password specified in the command field does not match the password of a file on adisk protected in Read mode, the CCP file open operation is terminated with a password error.
If the CCP does not find the command or submit file, it echoes the command line followed by a question markto the console. If it finds a command file with a filetype of COM or PRL, the CCP proceeds to step 4. If it finds
a submit file, it reconstructs the command line as described above, and repeats step 3 for the command,
SUBMIT.COM.
4. When the CCP successfully opens the command file, it initializes the following Page Zero fields for accessby the loaded transient program:
0050H Drive that the command file was loaded from
0051H Password address of first file in command tail0053H Password length of first file in command tail0054H Password address of second file in command tail0056H Password length of second file in command tail005CH Parsed FCB for first file in command tail006CH Parsed FCB for second file in command tail0080H Command tail preceded by command tail length
Page Zero initialization is covered in more detail in Section 2.4.
5. At this point, the CCP calls the LOADER module to load the command file into the TPA. The LOADER
module terminates the load operation if a read error occurs, or if the available TPA space is not large enough tocontain the file. If no RSXs are resident in memory, the available TPA space is determined by the addressDigital Research : CP/M 3 Programmer’s Manual

Page 18

LOADER base because the LOADER cannot load over itself. Otherwise, the maximum TPA address isdetermined by the base address of the lowest RSX in memory.
6. Once the program is loaded, the LOADER module checks for a RSX header on the program. Programs with
RSX headers are identified by a return instruction at location 100H. If an RSX header is present, the LOADER
relocates all RSXs attached to the end of the program, to the top of the TPA region of memory under the
LOADER module, or any other RSXs that are already resident. It also updates the address in location 0006H ofPage Zero to address the lowest RSX in memory. Finally, the LOADER discards the RSX header and relocatesthe program file down one page in memory so that the first executable instruction resides at 100H.
7. After initializing Page Zero, the LOADER module sets up a 32-byte stack with the return address set tolocation 0000H of Page Zero and jumps to location 100H. At this point, the loaded transient program begins
execution. When a transient program terminates execution, the BIOS warm start routine reloads the CCP intomemory. When the CCP receives control, it tests to see if RSXs are resident in memory. If not, it relocates the
LOADER module below the BDOS module at the top of the TPA region of memory. Otherwise, it skips thisstep because the LOADER module is already resident. The CCP execution cycle then repeats. Unlike earlier
versions of CP/M, the CCP does not reset the disk system at warm start. However, the CCP does reset the disk
system if a CTRL-C is typed at the prompt.

1.6.3 Transient Program Operation
A transient program is one that the CCP loads into the TPA region of memory and executes. As the nametransient implies, transient programs are not system resident. The CCP must load a transient program intomemory every time the program is to be executed. For example, the utilities PIP and RMAC" that are shippedwith CP/M 3 execute as transient programs; programs such as word processing and accounting packages
distributed by applications vendors also execute as transient programs under CP/M 3.
Section 1.6.2 describes how the CCP prepared the CP/M 3 environment for the execution of a transient
program. To summarize, the CCP initializes Page Zero to contain parsed command-line fields and sets up a 32byte stack before jumping to location 0100H to pass control to the transient program. In addition, the CCP
might also load RSXs attached to the command file into memory for access by the transient program.
Generally, an executing transient program communicates with the operating system only through BDOS
function calls. Transient programs make BDOS function calls by loading the CPU registers with the appropriate
entry parameters and calling location 0005H in Page Zero.
Transient programs can use BDOS Function 50, Call BIOS, to access BIOS entry points. This is the preferred
method for accessing the BIOS; however, for compatibility with earlier releases of CP/M, transient programs
can also make direct BIOS calls for console and list I/O by using the jump instruction at location 0000H in Page
Zero. But, to simplify portability, use direct BIOS calls only where the primitive level of functionality provided
by the BIOS functions is absolutely required. For example, a disk formatting program must bypass CP/M's disk
organization to do its job, and therefore is justified in making direct BIOS calls. Note however, that disk
formatting programs are rarely portable.
A transient program can terminate execution in one of three ways: by jumping to location 0000H, by making a
BDOS System Reset call, or by making a BDOS Chain To Program call. The first two methods are equivalent;
they pass control to the BIOS warm start entry point, which then loads the CCP into the TPA, and the CCP
prompts for the next command.
The Chain to Program call allows a transient program to specify the next command to be executed before it
terminates its own execution. A Program Chain call executes a standard warm boot sequence, but passes thecommand specified by the terminating program to the CCP in such a way that the CCP executes the specified
command instead of prompting the console for the next command.

Digital Research : CP/M 3 Programmer’s Manual

Page 19

Transient programs can also set a Program Return Code before terminating by making a BDOS Function 108
call, Get/Set Program Return Code. The CCP initializes the Program Return Code to zero, successful, when it
loads a transient program, unless the program is loaded as the result of a program chain. Therefore, a transient
program that terminates successfully can use the Program Return Code to pass a value to a chained program. If
the program terminates as the result of a BDOS fatal error, or a CTRL-C entered at the console, the BDOS sets
the return code to an unsuccessful value. All other types of program termination leave the return code at its
current value. The CCP has a conditional command facility that uses the Program Return Code.
If a command line submitted to the CCP by the SUBMIT utility begins with a colon, the CCP skips executionof the command if the previous command set an unsuccessful Program Return Code. In the following example,
the SUBMIT utility sends a command sequence to the CCP:
A>SUBMIT SUBFILE
A>COMPUTE RESULTS.DATA>REPORT RESULTS.DATThe CCP does not execute the REPORT command if the COMPUTE command sees an unsuccessful Program
Return Code.

1.6.4 Resident System Extension Operation
This section gives a general overview of RSX use, then describes how RSXs are loaded, defines the RSX filestructure, and tells how the LOADER module uses the RSX prefix and flags to manage RSX activity.
A Resident System Extension (RSX) is a special type of program that can be attached to the operating system tomodify or extend the functionality of the BDOS. RSX modules intercept BDOS functions and either performthem, translate them into other BDOS functions, or pass them through untouched. The BDOS executes nonintercepted functions in the standard manner.
A transient program can also use BDOS Function 60, Call Resident System Extension, to call an RSX for
special functions. Function 60 is a general purpose function that allows customized interfaces between
programs and RSXS.
Two examples of RSX applications are the GET utility and the LOADER module. The GET.COM command
file has an attached RSX, GET.RSX, which intercepts all console input calls and returns characters from the filespecified in the GET command line. The LOADER module is another example of an RSX, but it is special
because it supports Function 59, Load Overlay. It is always resident in memory when other RSXs are active.
RSXs are loaded into memory at program load time. As described in Section 1.6.2, after the CCP locates acommand file, it calls the LOADER module to load the program into the TPA. The LOADER loads thetransient program into memory along with any attached RSXS. Subsequently, the loader relocates each attached
RSX to the top of the TPA and adjusts the TPA size by changing the jump at location 0005H in Page Zero topoint to the RSX. When RSX modules reside in memory, the LOADER module resides directly below the
BDOS, and the RSX modules stack downward from it.
The order in which the RSX modules are stacked affects the order in which they intercept BDOS calls. A more
recently stacked RSX has precedence over an older RSX. Thus,, if two RSXs in memory intercept the same
BDOS function, the more recently loaded RSX handles the function.
The CP/M 3 utility GENCOM attaches RSX modules to program files. Program files with attached RSXs havea special one page header that the LOADER recognizes when it loads the command file. GENCOM can also
attach one or more RSXs to a null command file so that the CCP can load RSXs without having to execute atransient program. In this case, the command file consists of the RSX header followed by the RSXS.

Digital Research : CP/M 3 Programmer’s Manual

Page 20

RSX modules are Page Relocatable, PRL, files with the file type RSX. RSX files must be page relocatablebecause their execution address is determined dynamically by the LOADER module at load time. RSX files
have the following format:

Figure 1-8. RSX File Format
RSX files begin with a one page PRL header that specifies the total size of the RSX prefix and code sections.
The PRL bit map is a string of bits identifying those bytes in the RSX prefix and code sections that require
relocation. The PRL format is described in detail in Appendix B. Note that the PRL header and bit map are
removed when an RSX is loaded into memory. They are only used by the LOADER module to load the RSX.
The RSX prefix is a standard data structure that the LOADER module uses to manage RSXs (see Section 4.4).
Included in this data structure are jump instructions to the previous and next RSX in memory, and two flags.
The LOADER module initializes and updates these jump instructions to maintain the link from location 6 ofPage Zero to the BDOS entry point. The RSX flags are the Remove flag and the Non-banked flag. The Remove
flag controls RSX removal from memory. The CCP tests this flag to determine whether or not it should remove
the RSX from memory at system warm start. The non-banked flag identifies RSXs that are loaded only in nonbanked CP/M 3 systems. For example, the CP/M 3 RSX, DIRLBL.RSX, is a non-banked RSX. It provides
BDOS Function 100, Set Directory Label, support for non-banked systems only. Banked systems support thisfunction in the BDOS.
The RSX code section contains the main body of the RSX. This section always begins with code to intercept
the BDOS function that is supported by the RSX. Non-intercepted functions are passed to the next RSX in
memory. This section can also include initialization and termination code that transient programs can call with
BDOS Function 60.
When the CCP gains control after a system warm start, it removes any RSXs in memory that have the Remove
flag set to 0FFH. All other RSXs remain active in memory. Setting an RSX's Remove flag to 0FFH indicatesthat the RSX is not active and it can be removed. Note that if an RSX marked for removal is not the lowest
active RSX in memory, it still occupies memory after removal. Although the removed RSX cannot be executed,
its space is returned to the TPA only when all the lower RSXs are removed.
There is one special case where the CCP does not remove an RSX with the Remove flag set to 0FFH following
warm start. This case occurs on warm starts following the load of an empty file with attached RSXS. This
exception allows an RSX with the Remove flag set to be loaded into memory before a transient program. The
transient program can then access the RSX during execution. After the transient program terminates, however,
the CCP removes the RSX from the system environment.
As an example of RSX operation, here is a description of the operation of the GET utility. The GET.COM
command file has an attached RSX. The LOADER moves this RSX to the top of the TPA when it loads theDigital Research : CP/M 3 Programmer’s Manual

Page 21

GET.COM command file. The GET utility performs necessary initializations which include opening the ASCII
file specified in the GET command line. It also makes a BDOS Function 60 call to initialize the GET.RSX. At
this point, the GET utility terminates. Subsequently, the GET.RSX intercepts all console input calls and returns
characters from the file specified in the GET command line. It continues this action until it reads end-of-file. At
this point, it sets its Remove flag in the RSX prefix, and stops intercepting console input. On the following
warm boot, the CCP removes the RSX from memory.

1.6.5 SUBMIT Operation
A SUBMIT command line has the following syntax:
SUBMIT <filespec> <parameters>

If the CCP identifies a command as a submit file, it automatically inserts the SUBMIT keyword into thecommand line as described in Section 1.6.2.
When the SUBMIT utility begins execution, it opens and reads the file specified by <filespec> and creates a
temporary submit file of type $$$ on the system's temporary file drive. GENCPM initializes the temporary filedrive to the CCP's current default drive. The SETDEF utility can set the temporary file drive to a specific drive.
As it creates the temporary file, SUBMIT performs the parameter substitutions requested by the <parameters>
subfield of the SUBMIT command line. See the CP/M Plus (CP/M Version 3) Operating System User's Guide
for a detailed description of this process.
After SUBMIT creates the temporary submit file, its operation is similar to that of the GET utility described in
Section 1.6.4. The SUBMIT command file also has an attached RSX that performs console input redirection
from a file. However, the SUBMIT RSX expands upon the simpler facilities provided by the GET RSX.
Command lines in a submit file can be marked to indicate whether they are program or CCP input.
Furthermore, if a program exhausts all its program input, the next SUBMIT command is a CCP command, the
SUBMIT RSX temporarily reverts to console input. Redirected input from the submit file resumes when the
program terminates.
Because CP/M 3's submit facility is implemented with RSXS, submit files can be nested. That is) a submit file
can contain additional SUBMIT or GET commands. Similarly, a GET command can specify a file that contains
GET or SUBMIT commands. For example, when a SUBMIT command is encountered in a submit file, a new
SUBMIT RSX is created below the current RSX. The new RSX handles console input until it reads end-of-fileon its temporary submit file. At this point, control reverts to the previous SUBMIT RSX.

1.7 System Control Block
The System Control Block, SCB, is a 100 byte CP/M 3 data structure that resides in the BDOS systemcomponent. The SCB contains internal BDOS flags and data, CCP flags and data, and other system informationsuch as console characteristics and the current date and time. The BDOS, BIOS, CCP system components aswell as CP/M 3 utilities and RSXs reference SCB fields. BDOS Function 49, Get/Set System Control Block,provides access to the SCB fields for transient programs, RSXS, and the CCP.
However, use caution when you access the SCB through Function 49 for two reasons. First, the SCB is a CP/M
3 data structure. Digital Research's multi-user operating system, MP/M, does not support BDOS Function 49.
Programs that access the SCB can run only on CP/M 3. Secondly, the SCB contains critical system parametersthat reflect the current state of the operating system. If a program modifies these parameters illegally, theoperating system might crash. However, for application writers who are writing system-oriented applications,access to the SCB variables might prove valuable.

Digital Research : CP/M 3 Programmer’s Manual

Page 22For example, the CCP default drive and current user number are maintained in the System Control Block. This
information is displayed in the system prompt. If a transient program changes the current disk or user number
by making an explicit BDOS call, the System Control Block values are not changed. They continue to reflect
the state of the system when the transient program was loaded. For compatibility with CP/M Version 2, thecurrent disk and user number are also maintained in location 0004H of Page Zero. The high-order nibble
contains the user number, and the low-order nibble contains the drive.
Refer to the description of BDOS Function 49 in Section 2.5 for more information on the System Control
Block. The SCB fields are also discussed in Appendix A.

Digital Research : CP/M 3 Programmer’s Manual

Page 23

Section 2 : The BDOS System Interface
This section describes the operating system services available to a transient program through the BDOS moduleof 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.

2.1 BDOS Calling Conventions
CP/M 3 uses a standard convention for BDOS function calls. On entry to the BDOS, register C contains theBDOS 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 non-supported 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 theIntel 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 registervalues rests with the calling program. When the CCP loads a transient program, the LOADER module sets thestack pointer to a 16 level stack, and then pushes the address 0000H onto the stack. Thus, an immediate returnto the system is equivalent to a jump to 0000H. However, most transient programs set up their own stack, andterminate 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
conin equ 1
org 100h
nextc: mvi c,conin
call bdos
cpi '*'
jnz nextc
retend; BDOS entry Point in Page Zero
; BDOS console input function; Base of Transient Program Area
; Return character in A
; End of Processing?
; Loop if not; Terminate Program

2.2 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:


CONIN: logical console input device
CONOUT: logical console output device
AUXIN: logical auxiliary input device
AUXOUT: logical auxiliary output device
LST: logical list output device

If your system supports the BIOS DEVTBL function, the CP/M 3 DEVICE utility can display and change theassignment of logical devices to physical devices. DEVICE can also display the names and attributes ofDigital Research : CP/M 3 Programmer’s Manual

Page 24

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 andfrom these devices, or test the device's ready status. For these BDOS functions, a string of characters is definedas 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:
Read a character buffer from CONIN:
Write a character to CONOUT:
Write a string of characters to CONOUT:
Write a block of characters to CONOUT:
Read a character from AUXIN:
Write a character to AUXOUT:
Write a character to LST:
Write a block of characters to LST:Interrogate CONIN:, AUXIN:, AUXOUT: ready

CP/M 3 cannot run unless CONIN: and CONOUT: are assigned to a physical console. The remaining logicaldevices 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 (lAH), which indicates end-of-file. Note thatthese actions depend on your system's BIOS implementation.

2.2.1 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 PO 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:
1 Console Input
2 Console Output
9 Print String
11 Console Status
111 Print Block

Inputs a single character
Outputs a single character
Outputs a string of characters
Signals if a character is ready for input
Outputs a block of characters

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

Digital Research : CP/M 3 Programmer’s Manual

Page 25

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, thesecharacters 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 insituations 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 non-banked
version of CP/M 3, editing within the buffer is restricted to the last character on the line. That. is, to edit acharacter 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 canalso 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 inthe line, Function 10 terminates the calling program by branching to the BIOS warm start entry point. A CTRLC in any other position is simply echoed at the console. Function 10 also watches for a CTRL-P keystroke, andif 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:109. Get/Set Console Mode110. Get/Set Output Delimiter

Function 110 can get or set the current delimiter for Function 9, Print String. The delimiter is $, when atransient 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:

bit 0

bit 1

If this bit is set, Function 11 returns true only if a CTRL-C is typed at the console. Programs
that make repeated console status calls to test if execution should be interrupted, can set this bit
to interrupt on CTRL-C only. The CCP DIR and TYPE built-in commands run in this mode.
Setting this bit disables stop and start scroll support for the basic console 110 functions, which
comprise the first category of functions described in this section. When this bit is set, Function
1 reads CTRL-S, CTRL-Q, and CTRL-P, and Function 1 1 returns true if the user types thesecharacters. Use this mode in situations where raw console input and edited output is needed.
While in this mode, you can use Function 6 for input and input status, and Functions 1, 9, and
111 for output without the possibility of the output functions intercepting input CTRL-S,
CTRL-Q, or CTRL-P characters.

Digital Research : CP/M 3 Programmer’s Manual

Page 26

Setting this bit disables tab expansion and printer echo support for Functions 2, 9, and 111. Use
this mode when non-edited output is required.
This bit disables all CTRL-C intercept action in the BDOS. This mode is useful for programs
bit 3that must control their own termination.
The BDOS does not use these bits, but reserves them for the CP/M 3 GET RSX that performs
console input redirection from a file. With one exception, these bits determine how the GETRSX responds to a program console status request (Function 6, Function 11, or direct BIOS).
bits 8 and 9 bit 8 = 0, bit 9 = 0 conditional status
bit 8 = 0, bit 9 = 1 false status
bit 8 = 1, bit 9 = 0 true status
bit 8 = 1, bit 9 = 1 do not perform redirection
bit 2

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 thatspins on status to wait for a character is signaled that a character is ready on the second call. In addition, aprogram 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,, theCP/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 tochange the program.

2.2.2 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 thesefunctions. Note that AUXIN: and AUXOUT: replace the READER and PUNCH devices supported by earlier
versions of CP/M.

2.3 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 detailpresented in this section.
The remaining introductory paragraphs define the four categories of BDOS file functions. This is followed by areview of file naming conventions and disk and file organization. The section then describes the data structureused 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 De-blocking, 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 thecontents 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

Digital Research : CP/M 3 Programmer’s Manual

Page 27

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 apassword 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 e related functions require a specific filereference.
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 non-banked
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/De-blocking buffers. Also included arefunctions that set the BDOS multi-sector count, and the BDOS error mode. The BDOS multi-sector countdetermines 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 systemDisk System Reset
Drive Selection
File Creation
File Open
File Close
Directory Search
File Delete
File Rename
Random or Sequential Read
Random or Sequential Write
Interrogate Selected DisksSet DMA Address
Set/Reset File Attributes
Reset Drive
Set BDOS Multi-Sector CountSet BDOS Error ModeGet Disk Free Space
Chain to Program
Flush Buffers
Get/Set System Control Block
Call BIOS
Load Overlay
Call RSX
Truncate FileSet Directory Label
Get File's Date Stamps and Password Mode
Write File XFCB
Set/Get Date and TimeSet Default Password
Return CP/M 3 Serial Number
Get/Set Program Return Code
Parse Filename

2.3.1 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:{d:}filename{.typ}{;password}

Digital Research : CP/M 3 Programmer’s Manual

Page 28

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 aredetermined by the BIOS implementation. When the drive letter is not specified, the current default drive isassumed.
The filename and password fields can contain one to eight non-delimiter characters. The filetype field cancontain one to three non-delimiter characters. All three fields are padded with blanks, if necessary. Omitting theoptional 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
ASCII HEX EQUIVALENT
null

00

space

20

return

0D

tab

09

:

3A

.

2E

;

3B

=

3D

,

2C

[

5B

]

5D

<

3C

>

3E

|

7C

Function 152 also excludes all control characters from the file fields, and translates all lower-case letters toupper-case.
Avoid using parentheses and the backslash character, \, in the filename and filetype fields because they arecommonly used delimiters. Use asterisk and question mark characters, * and ?, only to make an ambiguous filereference. When Function 152 encounters an * in a filename or filetype field, it pads the remainder of the fieldwith 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:Digital Research : CP/M 3 Programmer’s Manual

Page 29

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.
ASM Assembler Source
PLI PL/I Source File
PRN Printer Listing
REL Relocatable Module
HEX Hex Machine CodeTEX TEX Formatter Source
BAS Basic Source File
BAK ED Source Backup
INT Intermediate FileSYM SID Symbol FileCOM Command File$$$ Temporary File
PRL Page Relocatable
DAT Data FileSPR Sys. Page Reloc.
SYS System File

2.3.2 Disk and File Organization
The BDOS file system can support from one to sixteen logical drives. The maximum file size supported on adrive is 32 megabytes. The maximum capacity of a drive is determined by the data block size specified for thedrive 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
Data Block Size Maximum Drive Capacity
1K

256 Kilobytes

2K

64 Megabytes

4K

128 Megabytes

8K

256 Megabytes

16K

512 Megabytes

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

Digital Research : CP/M 3 Programmer’s Manual

Page 30

contains entries that define which files exist on the drive. The directory entries corresponding to a particular filedefine 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 inthe 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 filecreated 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, notsequentially. Note that any data block allocated to a file is permanently allocated to the file until the file isdeleted 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 isfollowed 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, 1AH, or a realend of file, returned by the BDOS read operation. CTRL-Z characters embedded within machine code files suchas COM files are ignored. The actual end-of-file condition returned by the BDOS is used to terminate read
operations.

2.3.3 File Control Block Definition
The File Control Block, FCB, is a data structure that is set up and initialized by a transient program, and thenused 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 aprogram opens a file, and subsequently accesses it with BDOS read and write record functions, the BDOS filesystem 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 thecalling 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 on the next page.

whereDigital Research : CP/M 3 Programmer’s Manual

Page 31drive code (0 - 16)
dr

0 = > use default drive for file
1 = > auto disk select drive A,
2 = > auto disk select drive B,
16 = > auto disk select drive P.

fl ... f8

contain the filename in ASCII upper-case, with high bit = 0.

f1... f8

denote the high-order bit of these positions, and are file attribute bits.

tl,t2,t3

contain the filetype in ASCII upper-case, with high bit = 0. t1, t2 and t3 denote the high bit ofthese positions, and are file attribute bits.
t1 = 1 = > Read/Only file t2 = 1 = > System file t3 = 1 = > File has been archived

excontains the current extent number, usually set to 0 by the calling program, but can range 0 - 31
during file I/O

s1

reserved for internal system use

s2

reserved for internal system use

rc

record count for extent "ex" takes on values from 0 - 255 (values greater than 128 imply record
count equals 128)

d0 ... dn

filled-in by CP/M 3, reserved for system use

crcurrent record to read or write in a sequential file operation, normally set to zero by the calling
program when a file is opened or created

r0,rl,r2

optional random record number in the range 0-262,143 (0 - 3FFFFH). r0,rl,r2 constitute a 18 bit
value with low byte r0, middle byte r1, and high byte r2.

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 toinitialize byte 12. The Rename File function requires the calling program to place the new filename and type inbytes 17 through 27.
BDOS open or make function calls require the calling program to initialize bytes 0 through 12 of the FCB
before making the call. Usually, byte 12 is set to zero. In if the file is to be processed from the beginning using
sequential read or addition, 1 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 toperform 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 Filefunctions 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 allocationof data to the file, and at the termination of file processing, the Close File function permanently records this

Digital Research : CP/M 3 Programmer’s Manual

Page 32

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 thedrive 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 E5H is an empty directory entry.

2.3.4 File Attributes
The high-order bits of the FCB filename, f1,...,f8, and filetype, t1,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 arerecorded 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:
t1

Read-Only
attribute

The file system prevents write operations to a file with the read-only attribute set.

Systemt2
attribute

This attribute, if set, identifies the file as a CP/M 3 system file. System files are not usuallydisplayed by the CP/M 3 DIR command. In addition, user-zero system files can be accessed ona read-only basis from other user numbers.

Archive
attribute

This attribute is designed for user written archive programs. When an archive program copies afile 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 attributeset, it indicates that the file has not been modified since the previous archives Note that the
CP/M 3 PIP utility supports file archival.

t3

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
BDOS Function

Interface Attribute Definition

Digital Research : CP/M 3 Programmer’s Manual
16. Close File

f5 = 1 : Partial Close

19. Delete File

f5 = 1 : Delete file XFCBs only

22. Make Filef6 = 1 : Assign password to file

Page 33

30. Set File Attributes f6 = 1 : Set file byte countSection 3 discusses each interface attribute in detail in the definitions of the above functions. Attributes f5 andf6 are always reset when control is returned to the calling program. Interface attributes f7 and f8 are reservedfor internal use by the BDOS file system.

2.3.5 User Number Conventions
The CP/M 3 User facility divides each drive directory into sixteen logically independent directories, designatedas user 0 through user 15. Physically, all user directories share the directory area of a drive. In most otheraspects, 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 beaccomplished 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 inthis 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 arequested file is not present under the current user number, the file system automatically attempts to open thefile 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 forread access. This procedure allows utilities that may include overlays and any other commonly accessed files tobe 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.

2.3.6 Directory Labels and XFCBs
The BDOS file system includes two special types of FCBS: the XFCB and the Directory Label. The XFCB isan 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.

Digital Research : CP/M 3 Programmer’s Manual

Page 34

Figure 2-1. Extended FCB Format
drdrive code (0 - 16)

filefilename field

type

filetype fieldPM

password mode

bit 7

Read mode

bit 6

Write mode

bit 5

Delete mode**

bit references are right to left, relative to 0

s1, s2, rc reserved for system use
password 8-byte password field (encrypted)
reserved 8-byte reserved area
An XFCB can be created only on a drive that has a directory label, and only if the directory label has activatedpassword 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 thecalling 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 timestamping for files is to be performed. The format of the Directory Label follows.

Figure 2-2 : Directory Label Format
drdrive code (0 - 16)

nameDirectory Label nametype

Directory Label typedl

Directory Label data byte

bit 7

require passwords for password protected files

bit 6

perform access time stamping

bit 5

perform update time stamping

Digital Research : CP/M 3 Programmer’s Manual
bit 4

perform create time stamping

bit 0

Directory Label exists**

bit references are right to left, relative to 0

s1, s2, rc

n/a

password

8-byte password field (encrypted)

tsl

4-byte creation time stamp fieldts2

4-byte update time stamp field

Page 35

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 non-banked 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
non-banked 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 Labeldata 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 dri ve. In
the directory, the Directory Label is identified by a drive byte value, byte 0 in the FCB, equal to 32, 20H.

2.3.7 File Passwords
Only the banked version of CP/M 3 supports file passwords. In the non-banked 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
Password Access level allowed when the Password Mode is not supplied.
1. Read

The file cannot be read.

2. Write

The file can be read, but not modified.

3. Delete

The file can be modified, but not deleted.

If a file is password protected in Read mode, the password must be supplied to open the file. A file protected inWrite 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

Digital Research : CP/M 3 Programmer’s Manual

Page 36

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 andSearch 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
15

Open File

19

Delete File

23

Rename File30

Set File Attributes

99

Truncate File

100 Set Directory Label
103 Write File XFCBFile 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 thefirst 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.

2.3.8 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 SFCB Format
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.

Digital Research : CP/M 3 Programmer’s Manual

Page 37

The SFCB directory item contains five fields. The first field is one byte long and contains the value 21H. Thisvalue identifies the SFCB in the directory. The next three fields, the SFCB subfields, contain the date and timestamps for their corresponding FCB entries in the directory record. These fields are 10 bytes long. The last byteof 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
Offset in Bytes

SFCB Subfield Contents

0-3Create or Access Date and Time Stamp field

4-7

Update Date and Time Stamp field

8

Password mode field

9

Reserved

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 canreturn the file date and time stamps and password mode for a specified file. Refer to Section 3, function 102, fora 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 thismanner. 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 systemdate and time.

2.3.9 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

Digital Research : CP/M 3 Programmer’s Manual

Page 38component 128 byte logical records is called record De-blocking. This process is required in read operations.
Under CP/M 3, record blocking and De-blocking is normally performed by the BDOS.
Record De-blocking 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 t 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 thestate 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 De-blocking. If the system should crash while aphysical 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 asystem warm start. However, the BDOS file system automatically makes a Flush Buffers call in the Close Filefunction. Thus, it is sufficient to close a file to ensure that all pending physical buffers for that file are written to
the disk.

2.3.10 Multi-Sector I/O
CP/M 3 can read or write multiple 128-byte records in a single BDOS function call. This process, called multisector I/O, is useful primarily in sequential read and write operations, particularly on drives with physicalrecord sizes larger than 128 bytes. In a multi-sector I/O operation, the BDOS file system bypasses, whenpossible, 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 adrive. 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 theimplementation 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:Sequential Read and Write functions
Random Read and Write functions including Write Random with Zero Fill

If the multi-sector count is N, calling one of the above functions is equivalent to making N function calls. If amulti-sector I/O operation is interrupted with an error such as reading unwritten data, the file system returns inregister H the number of 128-byte records successfully processed.

2.3.11 Disk Reset and Removable Media

Digital Research : CP/M 3 Programmer’s Manual

Page 39

The BDOS functions, Disk Reset (function 13) and Reset Drive (function 37) allow a program to control whena 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 filesystem. 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 thesystem. 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 de-allocation of data blocks to files, as files
are created, extended, deleted, and truncated, Another function performed during drive log-in is theinitialization 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 nothave check-sum vectors. If directory hashing has been specified for the drive, a BIOS and GENCPM option, thefile 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 thedrive 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/De-blocking 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 re-logs in removable media when media changes are detected, the application
program should still explicitly reset a drive before prompting the user to change disks.

2.3.12 File Byte Counts
Although the logical record size of CP/M 3 is restricted to 128 bytes, CP/M 3 does provide a mechanism tostore 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 afile'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 sl field of the FCB returned in the current DMA buffer (seeBDOS 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.

2.3.13 BDOS Error Handling
The BDOS file system responds to error situations in one of three ways:
Method 1.
Method 2.
Method 3.

It returns to the calling program with return codes in register A, H, and L
identifying the error.
It displays an error message on the console, and branches to the BIOS warm
start entry point, thereby terminating execution of the calling program.
It displays an error message on the console, and returns to the calling program as

Digital Research : CP/M 3 Programmer’s Manual

Page 40in method 1.
The file system handles the majority of errors it detects by method 1. Two examples of this kind of error are thefile 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 andextended 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 andextended 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 inregisters A, H, and L, method 1. In return and display mode, the BDOS returns control to the calling programwith 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 returnand 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.typwhere 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 non-banked version of CP/M 3.
The BDOS physical errors are identified by the following error messages:Disk I/O
Invalid Drive
Read-Only File
Read-Only Disk

The Disk I/O error results from an error condition returned to the BDOS from the BIOS module. The filesystem 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 theBIOS 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 ReadOnly attribute. It is also returned to a program that attempts to write to a system file opened under user zerofrom a nonzero user number. In addition, this error is returned when a program attempts to write to a filepassword 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 beplaced in read-only status explicitly with the BDOS Write Protect Disk function. The BDOS extended errors
are identified by the following error messages:Password Error
File Exists? in Filename

Digital Research : CP/M 3 Programmer’s Manual

Page 41

The File Password error is returned when the file password is not supplied, or when it is incorrect. This error isreported 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, aDirectory Code, or an Error Flag. The error conventions of CP/M 3 are designed to allow programs written forearlier versions of CP/M to run without modification.
The following BDOS functions return an Error Code in register A.






20. Read Sequential
21. Write Sequential
33. Read Random
34. Write Random
40. Write Random w/Zero Fill

The Error Code definitions for register A are shown in Table 2-7.
Table 2-7. Register A BDOS Error Codes
CodeMeaning00

Function successful

255

Physical error : refer to register H

01

Reading unwritten data or no available directory space (Write Sequential)

02

No available data block03

Cannot close current extent

04

Seek to unwritten extent

05

No available directory space

06

Random record number out of range

09

Invalid FCB (previous BDOS close call returned an error code and invalidated the FCB)

10Media Changed (A media change was detected on the FCB's drive after the FCB was opened)

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:

Digital Research : CP/M 3 Programmer’s Manual














Page 42

15. Open File
16. Close File
17. Search For First
18. Search For Next
19. Delete File
22. Make File
23. Rename File
30. Set File Attributes
35. Compute File Size
99. Truncate File
100. Set Directory Label102. Read File Date Stamps and Password Mode** 103. Write File XFCB

* - This function is supported in the DIRLBL.RSX in the non-banked version of CP/M 3.
** - This function is supported only in the banked version of CP/M 3.
The Directory Code definitions for register A are shown in Table 2-8.
Table 2-8. BDOS Directory Codes
CodeMeaning

00 - 03 successful function
255

unsuccessful function

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:






14. Select Disk
46. Get Disk Free Space
48. Flush Buffers
98. Free Blocks
101. Return Directory Label Data

The Error Flag definition for register A is shown in Table 2-9.
Table 2-9. BDOS Error Flags
CodeMeaning00

successful function

255

physical error : refer to register H

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

Digital Research : CP/M 3 Programmer’s Manual

Page 43

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

Meaning00

no error, or not a register H error

01

Disk I/O error

02

Read-Only Disk

03

Read-Only File or File Opened under user zero from another user number or filepassword protected in write mode and correct password not specified.

04

Invalid Drive : drive select error

07

Password Error

08

File Exists

09? in Filename

The following two functions represent a special case because they return an address in registers H and L.


27. Get Addr(Alloc)
31. Get Addr(Disk Parms)

When the BDOS is in return error mode, and it detects a physical error for these functions, it returns to thecalling program with registers A, H, and L all set to 255.
Otherwise, they return no error code.

2.4 Page Zero Initialization
Page Zero is the region of memory located from 0000H to 00FFH. This region contains several segments ofcode and data that are used by transient programs while running under CP/M 3. The code and data areas areshown in Table 2-11 for reference.
Table 2-11. Page Zero Areas
Location
From

TO

Contents

0000H

Contains a jump instruction to the BIOS warm start entry point at BIOS_base + 3. The
0002H address at location 0001H can also be used to make direct BIOS calls to the BIOS
console status, console input, console output, and list output primitive functions.

0003H

0004H (Reserved)

0005H

Contains a jump instruction to the BDOS, the LOADER, or to the most recently added
RSX, and serves two purposes: JMP 0005H provides the primary entry point to the0007H BDOS, and LHLD 0006H places the address field of the jump instruction in the HLregister pair. This value, minus one, is the highest address of memory available to thetransient program.

Digital Research : CP/M 3 Programmer’s Manual
0008H

003AH Reserved interrupt locations for Restarts 1 - 7

003BH

004FH (Not currently used - reserved)

Page 44

Identifies the drive from which the transient program was loaded. A value of one to
sixteen identifies drives A through P.

0050H

0051H

Contains the address of the password field of the first command-tail operand in the0052H default DMA buffer beginning at 0080H. The CCP sets this field to zero if no password
for the first command-tail operand is specified.

0053H

Contains the length of the password field for the first command-tail operand. The CCP
also sets this field to zero if no password for the first command tail is specified.

0054H

0055H

Contains the address of the password field of the second command-tail operand in thedefault DMA buffer beginning at

0080H

The CCP sets this field to zero if no password for the second command-tail operand isspecified.

0056H

Contains the length of the password field for the second command-tail operand. The
CCP also sets this field to zero if no password for the second command tail is specified.

0057H

005BH (Not currently used - reserved)

005CH

007BH

006CH

Default File Control Block, FCB, area 2 initialized by the CCP from the second
command-tail operand of the command line, if it exists. Note: this area overlays the last
007BH
16 bytes of default FCB area 1. To use the information in this area, a transient program
must copy it to another location before using FCB area 1.

007CH

Current record position of default FCB area 1. This field is used with default FCB area 1
in sequential record processing.

Default File Control Block, FCB, area 1 initialized by the CCP from the first commandtail operand of the command line, if it exists.

007DH

007FH

Optional default random record position. This field is an extension of default FCB area
1 used in random record processing.

0080H

00FFH

Default 128-byte disk buffer. This buffer is also filled with the command tail when the
CCP loads a transient program.

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 indetail in Section 1.6.2. To summarize, a command line usually takes the form:<command> <command tail>where<command> = <file Spec><command tail> = > (no command tail)= > <file Spec>= > <file spec><delimiter><file spec><file spec> = > {d:}filename{.type} {;password}

Digital Research : CP/M 3 Programmer’s Manual

Page 45

The CCP initializes the command drive field at 0050H to the drive index, A = 1, P = 16, of the drive fromwhich 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 through0053H 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, atransient 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 thecommand 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 tobinary 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 DMAI, the BDOS file system moves 128byte 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 thecommand 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 thefollowing 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........
0050H: 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.

Digital Research : CP/M 3 Programmer’s Manual

Page 46

Digital Research : CP/M 3 Programmer’s Manual

Page 47

Section 3 : BDOS Function Calls
This section describes each CP/M 3 system function, including the parameters a program must pass whencalling the function, and the values the function returns to the program. The functions are arranged numericallyfor easy reference. You should be familiar with the BDOS calling conventions and other concepts presented in
Section., before referencing this section.

BDOS FUNCTION 0: SYSTEM RESET
Entry Parameters:
Register C: 00H

Description:
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 areturn 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

Description:
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 theconsole. Tab characters, CTRL-I, are expanded in columns of 8 characters. CTRL-S, CTRL-Q, andCTRL-P are normally intercepted as described below. All other non-graphic characters are returned inregister 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 notintercepted. 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:.

Digital Research : CP/M 3 Programmer’s Manual

Page 48

Function 1 does not return control to the calling program until a non-intercepted character is typed, thussuspending execution if a character is not ready.

BDOS FUNCTION 2: CONSOLE OUTPUT
Entry Parameters:
Registers C: 02H
E: ASCII Character

Description:
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-1, 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

Description:
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 until the character is read.

BDOS FUNCTION 4: AUXILIARY OUTPUT
Entry Parameters:
Registers C: 04H
E: ASCII Character

Description:
The Auxiliary Output function sends the ASCII character from register E to the logical auxiliary output
device, AUXOUT:.

Digital Research : CP/M 3 Programmer’s Manual

Page 49

BDOS FUNCTION 5: LIST OUTPUT
Entry Parameters:
Registers C: 05H
E: ASCII Character

Description:
The List Output function sends the ASCII character in register E to the logical list device, LST:.

BDOS FUNCTION 6: DIRECT CONSOLE I/0
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 (no value)

Description:
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 00 if no character isready; otherwise it contains 0FFH.)

0FDH

Console input command, returns an input character; this function will suspend thecalling process until a character is ready.

Digital Research : CP/M 3 Programmer’s Manual

ASCII

Page 50Function 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

Description:
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 0FH isreturned.

BDOS FUNCTION 8: AUXILIARY OUTPUT STATUS
Entry Parameters:
Register C: 08H

Returned Value:
Register A: Auxiliary Output Status

Description:
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, thevalue 0FH is returned.

BDOS FUNCTION 9: PRINT STRING
Entry Parameters:
Registers C: 09H
DE: String Address

Description:

Digital Research : CP/M 3 Programmer’s Manual

Page 51

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-1, 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

Description:
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, CTRLG, 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:### Scan and insert illustration here.
where mx is the maximum number of characters which the buffer holds, and nc is the number ofcharacters 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 tozero 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 includedin the count nc.
If register pair DE is set to zero, Function 10 assumes that an initialized input buffer is located at thecurrent 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 cl 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 theconsole. 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 non-banked versions of
CP/M 3. Refer to the CP/M Plus (CP/M Version 3) Operating System User's Guide for a detailed

Digital Research : CP/M 3 Programmer’s Manual

Page 52

description of console editing. In the non-banked version, Function 10 recognizes the edit control
characters summarized in Table 3-2.
Table 3-2. Edit Control Characters (Non-banked CP/M 3)
Character

Edit Control Function

rub/delRemoves 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 non-banked 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 theprevious 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/delRemoves and echoes the last character if at the end of the line; otherwise deletes thecharacter 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, thecharacters 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 noeffect 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.

Digital Research : CP/M 3 Programmer’s Manual

Page 53

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; deletescurrent 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 isinserted 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

Description:
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:

Digital Research : CP/M 3 Programmer’s Manual

Page 54

Register C: 0CH

Returned Value:
Register HL: Version Number

Description:
The Return Version Number function provides information that allows version independent
programming. It returns a two-byte value in register pair HL: H contains 0FH for CP/M and L contains
31H, 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

Description:
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 diskchanges during operation. Function 37, Reset Drive, can also be used for this purpose.

BDOS FUNCTION 14: SELECT DISK
Entry Parameters:
Register C: 0EH

Returned Value:
E: Selected Disk
Registers A: Error Flag
H: Physical Error

Description:
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 thereset state. Logging-in a drive activates the drive's directory until the next disk system reset or drive
reset operation.

Digital Research : CP/M 3 Programmer’s Manual

Page 55

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 anddirectly 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 (seeFunction 45). If the BDOS error mode is in the default mode, a message identifying the error isdisplayed at the console, and the calling program is terminated. Otherwise, the select function returns tothe 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 15: OPEN FILE
Entry Parameters:
Registers C: 0FH
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical or Extended Error

Description:
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 eightbytes 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 thelast 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 firstrecord.
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 inWrite mode, and the correct password was not passed in the DMA, or did not match the default

Digital Research : CP/M 3 Programmer’s Manual

Page 56

password, interface attribute f7 is set to one. Write operations are not supported for an activated FCB ifinterface attribute f7 or f8 is true.
When the open operation is successful, the open function also makes an Access date and time stamp forthe opened file when the following conditions are satisfied: the referenced drive has a directory labelthat 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 0FH if the open
was successful, or 0FFH, 255 decimal, if the file was not found. Register H is set to zero in both of thesecases. 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, amessage identifying the error is displayed at the console and the program is terminated. Otherwise, theOpen File function returns to the calling program with register A set to 0FFH, and register H set to oneof the following physical or extended error codes:
01 Disk I/O error
04 Invalid drive error
07 File password error
09 ? in filename or filetype field

BDOS FUNCTION 16: CLOSE FILE
Entry Parameters:
Registers C: 10H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical or Extended Error

Description:
The Close File function performs the inverse of the Open File function. The calling program passes theaddress of an FCB in register pair DE. The referenced FCB must have been previously activated by asuccessful 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 openstate.
If the referenced FCB contains new information because of write operations to the FCB, the closefunction permanently records the new information in the referenced disk directory. Note that the FCB

Digital Research : CP/M 3 Programmer’s Manual

Page 57

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 thesecases. 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, amessage 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: 11H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical Error

Description:
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 thestandard 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 becalled repeatedly to locate all remaining matching entries. In terms of execution sequence, however, theSearch For Next call must either follow a Search For First or Search For Next call with no otherintervening BDOS disk-related function calls.
If byte 0 of the referenced FCB is set to a question mark, the Search function ignores the remainder ofthe referenced FCB, and locates the first directory entry residing on the current default drive. Allremaining directory entries can be located by making multiple Search For Next calls. This type ofsearch operation is not usually made by application programs, but it does provide complete flexibility toscan all current directory values. Note that this type of search operation must be performed to access adrive's directory label (see Section 2.3.6).

Digital Research : CP/M 3 Programmer’s Manual

Page 58

Upon return, the Search function returns a Directory Code in register A with the value 0 to 3 if thesearch 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 inevery 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 atoffset 96 within the current DMA, contents of (DMA Address + 96) = 21H, 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, theSearch 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: 12H

Returned Value:
Registers A: Directory Code
H: Physical Error

Description:
The Search For Next function is identical to the Search For First function, except that the directory scancontinues 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.

Digital Research : CP/M 3 Programmer’s Manual

Page 59

BDOS FUNCTION 19: DELETE FILE
Entry Parameters:
Registers C: 13H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Extended or Physical Error

Description:
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 fl 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 beplaced in the first eight bytes of the current DMA buffer, or have been previously established as thedefault password (see Function 106).
For standard delete operations, the Delete function removes all directory entries belonging to files thatmatch the referenced FCB. All disk directory and data space owned by the deleted files is returned tofree space, and becomes available for allocation to other files. Directory XFCBs that were owned by thedeleted 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 fall the password check, or are ReadOnly, then the Delete function does not delete any files or XFCBS.
This applies to both types of delete operations.
In non-banked systems, file passwords and XFCBs are not supported. Thus, if the Delete function iscalled with interface attribute f5 set to true, the Delete function performs no action but returns withregister 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:

Digital Research : CP/M 3 Programmer’s Manual

Page 60

01 Disk I/O error
02 Read-Only disk
03 Read-Only file04 Invalid drive error
07 File password error

BDOS FUNCTION 20: READ SEQUENTIAL
Entry Parameters:
Registers C: 14H
DE: FCB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
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 thenumber of records to be read. The default is one record. The FCB addressed by register pair DE musthave 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 tothe next record position. If the cr field overflows, then the function automatically opens the next logicalextent 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

10Media 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 adata block that has not been previously written, or an extent which has not been created. Thesesituations are usually restricted to files created or appended with the BDOS random write functions (seeFunctions 34 and 40).
Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call that returns an error.

Digital Research : CP/M 3 Programmer’s Manual

Page 61

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, amessage 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 numberof 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: 15H
DE: FCB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
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 thenautomatically 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 alreadyexisting in the file. The calling program must set the cr field to 0 following an Open or Make call if theintent 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: thereferenced drive has a directory label that requests date and time stamping, and the file has not alreadybeen stamped for update by a previous Make or Write function call.

Digital Research : CP/M 3 Programmer’s Manual

Page 62

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

Reading unwritten data (end-of-file)02

No available data block09

Invalid FCB

10Media 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 activatedby 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, amessage 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 file04 Invalid drive error
On all error returns, except for physical error returns, A = 255, Function 21 sets register H to thenumber of records successfully written before the error was 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 set to one.

BDOS FUNCTION 22: MAKE FILE
Entry Parameters:
Registers C: 16H
DE: FCB Address

Returned Value:

Digital Research : CP/M 3 Programmer’s Manual

Page 63

Registers A: Directory Code
H: Physical or Extended Error

Description:
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 theextent number. Usually, byte 12 is set to zero. Byte 32 of the FCB, the cr field, must be initialized tozero, 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 thecurrent DMA buffer, and set byte 9 of the DMA buffer to the password mode (see Function 102). Notethat the Make function only interrogates interface attribute f6 if passwords are activated on thereferenced drive. In non-banked systems, file passwords are not supported, and attribute f6 is neverinterrogated.
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 tozero 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 thedefault 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

Digital Research : CP/M 3 Programmer’s Manual

Page 64

08 File already exists
09 ? in filename or filetype field

BDOS FUNCTION 23: RENAME FILE
Entry Parameters:
Registers C: 17H
DE: FCB Address

Returned Value-.
Registers A: Directory Code
H: Physical or Extended Error

Description:
The Rename function uses the FCB, addressed by register pair DE, to change all directory entries of thefile 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 thefirst 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, amessage identifying the error is displayed at the console and the program is terminated. Otherwise, theRename 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 file04 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: 18H

Digital Research : CP/M 3 Programmer’s Manual

Page 65

Returned Value:
Register HL: Login Vector

Description:
Function 24 returns the login vector in register pair HL. The login vector is a 16-bit value with the leastsignificant bit of L corresponding to drive A, and the high-order bit of H corresponding to the 16th
drive, labeled 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
compatibility with earlier releases since registers A and L contain the same values upon return.

BDOS FUNCTION 25: RETURN CURRENT DISK
Entry Parameters:
Register C: 19H

Returned Value:
Register A: Current Disk

Description:
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: 1AH
DE: DMA Address

Description:
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 toone (see Function 44), the size of the buffer is 128 bytes. However, if the BDOS Multi-Sector Count isgreater 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Digital Research : CP/M 3 Programmer’s Manual

Page 66

the current DMA. When the current DMA is used in this context, the size of the buffer in memory isdetermined 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 canchange this default value to another memory address. The DMA address is set to the value passed in theregister 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: 1BH

Returned Value:
Register HL: ALLOC Address

Description:
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: 1CH

Description:
The Write Protect Disk function provides temporary write protection for the currently selected disk bymarking 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 (seeFunctions 13 and 37).

Digital Research : CP/M 3 Programmer’s Manual

Page 67

BDOS FUNCTION 29: GET READ-ONLY VECTOR
Entry Parameters:
Register C: 1DH

Returned Value:
Register HL: R/O Vector Value

Description:
Function 29 returns a bit vector in register pair HL that indicates which drives have the temporary ReadOnly 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 leastsignificant bit corresponds to drive A, while the most significant bit corresponds to drive P.

BDOS FUNCTION 30: SET FILE ATTRIBUTES
Entry Parameters:
Registers C: 1EH
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical or Extended error

Description:
By calling the Set File Attributes function, a program can modify a file's attributes and set its last record
byte count. Other BDOS functions can be called to interrogate these file parameters, but only Function
30 can change them. The file attributes that can be set or reset by Function 30 are f1 through f4, ReadOnly, t1, System, t2, and Archive, t3. The register pair DE addresses an FCB containing a filenamewith the appropriate attributes set or reset. The calling program must ensure that it does not specify anambiguous filename. In addition, if the specified file 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 thedefault password (see Function 106).
Interface attribute f6 specifies whether the last record byte count of the specified file is to be set:
f6 = 0 Do not set byte count (default mode)
f6 = 1 Set byte countDigital Research : CP/M 3 Programmer’s Manual

Page 68

If interface attribute f6 is set, the calling program must set the cr field of the referenced FCB to the byte
count value. A program can access a file's byte count value with the BDOS Open, Search, or Search
Next functions.
Function 30 searches the referenced directory for entries belonging to the current user number thatmatches the FCB specified name and type fields. The function then updates the directory to contain theselected indicators, and if interface attribute f6 is set, the specified byte count value. Note that the lastrecord byte count is maintained in byte 13 of a file's directory FCBS.
File attributes t1, t2, and t3 are defined by CP/M 3. (They are described in Section 2.3.4.) Attributes f1
through f4 are not presently used, but can be useful for application programs, because they are not
involved in the matching program used by the BDOS during Open File and Close File operations.
Indicators f5 through f8 are reserved for use as interface attributes.
Upon return, Function 30 returns a Directory Code in register A with the value 0 if the function is
successful, or 0FFH, 255 Decimal, if the file specified by the referenced FCB is not found. Register H is
set to zero in both of these cases. If a physical or extended error is encountered, the Set File Attributes
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 theprogram is terminated. Otherwise, Function 30 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
07 File password error
09 ? in filename or filetype field

BDOS FUNCTION 31: GET ADDR(DPB PARMS)
Entry Parameters:
Register C: 1FH

Returned Value:
Register HL: DPB Address

Description:
Function 31 returns in register pair HL the address of the BIOS-resident Disk Parameter Block, DPB,
for the currently selected drive. (Refer to the CP/M Plus (CP/M Version 3) Operating System System
Guide for the format of the DPB). The calling program can use this address to extract the disk parametervalues.
If a physical error is encountered when the BDOS error mode is one of the return modes (see Function45), Function 31 returns the value 0FFFFH in the register pair HL.

Digital Research : CP/M 3 Programmer’s Manual

Page 69

BDOS FUNCTION 32: SET/GET USER CODE
Entry Parameters:
Registers C: 20H

Returned Value:
E: 0FFH (get) or User Code (set)Register A: Current Code or (no value)

Description:
A program can change, or interrogate the currently active user number by calling Function 32. If register
E = 0FFH, then the value of the current user number is returned in register A, where the value is in therange of 0 to 15. If register E is not 0FFH, then the current user number is changed to the value of E,
modulo 16.

BDOS FUNCTION 33: READ RANDOM
Entry Parameters:
Registers C: 21H
DE: FCB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
The Read Random function is similar to the Read Sequential function except that the read operation
takes place at a particular random record number, selected by the 24-bit value constructed from the threebyte, r0, r1, r2, field beginning at position 33 of the FCB. Note that the sequence of 24 bits is storedwith the least significant byte first, r0, the middle byte next, r1, and the high byte last, r2. The random
record number can range from 0 to 262,143. This corresponds to a maximum value of 3 in byte r2.
To read a file with Function 33, the calling program must first open the base extent, extent 0. This
ensures that the FCB is properly initialized for subsequent random access operations. The base extent
may or may not contain any allocated data. Function 33 reads the record specified by the random record
field into the current DMA address. The function automatically sets the logical extent and current record
values, but unlike the Read Sequential function, it does not advance the current record number. Thus, a
subsequent Read Random call rereads the same record. After a random read operation, a file can beaccessed sequentially, starting from the current randomly accessed position. However, the last randomly
accessed record is reread or rewritten when switching from random to sequential mode.
If the BDOS Multi-Sector Count is greater than one (see Function 44), the Read Random function reads
multiple consecutive records into memory beginning at the current DMA. The r0, r1, and r2 field of theDigital Research : CP/M 3 Programmer’s Manual

Page 70

FCB is automatically incremented to read each record. However, the FCBs random record number isrestored to the first record's value upon return to the calling program.
Upon return, the Read Random function sets register A to zero if the read operation was successful.
Otherwise, register A contains one of the following error codes:
01

Reading unwritten data (end-of-file)03

Cannot close current extent

04

Seek to unwritten extent

06

Random record number out of range

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 adata block that has not been previously written.
Error Code 03 is returned when the Read Random function cannot close the current extent prior to
moving to a new extent.
Error Code 04 is returned when a read random operation accesses an extent that has not been created.
Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 3.
Error Code 10 is returned if a media change occurs on the drive after the referenced FCB is activatedby a BDOS Open or Make Call.
Error Code 255 is returned if a physical error is encountered, and the BDOS error mode is one of the
return modes (see Function 45). If the error mode is the default mode, a message identifying thephysical 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 errors, A = 255, the Read Random function sets register H to thenumber 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 34: WRITE RANDOM
Entry Parameters:
Registers C: 22H

Digital Research : CP/M 3 Programmer’s Manual

Page 71

DE: FCB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
The Write Random function is analogous to the Read Random function, except that data is written to thedisk from the current DMA address. If the disk extent or data block where the data is to be written is notalready allocated, the BDOS automatically performs the allocation before the write operation continues.
To write to a file using the Write Random function, the calling program must first open the base extent,
extent 0. This ensures that the FCB is properly initialized for subsequent random access operations. If
the file is empty, the calling program must create the base extent with the Make File function before
calling Function 34. The base extent might or might not contain any allocated data, but it does record
the file in the directory, so that the file can be displayed by the DIR utility.
The Write Random function sets the logical extent and current record positions to correspond with therandom record being written, but does not change the random record number. Thus, sequential read or
write operations can follow a random write, with the current record being reread or rewritten as thecalling program switches from random to sequential mode.
Function 34 makes an Update date and time stamp for the file if the following conditions are satisfied:
the referenced drive has a directory label that requests Update date and time stamping if the file has notalready been stamped for update by a previous BDOS Make or Write call.
If the BDOS Multi-Sector Count is greater than one (see Function 44), the Write Random function reads
multiple consecutive records into memory beginning at the current DMA. The r0, r1, and r2 field of the
FCB is automatically incremented to write each record. However, the FCB's random record number isrestored to the first record's value when it returns to the calling program. Upon return, the Write
Random function sets register A to zero if the write operation is successful. Otherwise, register A
contains one of the following error codes:
02

No available data block03

Cannot close current extent

05

No available directory space

06

Random record number out of range

10

Media change occurred

255 Physical Error : refer to register H
Error Code 02 is returned when the write command attempts to allocate a new data block to the fileand no unallocated data blocks exist on the selected disk drive.
Error Code 03 is returned when the Write Random function cannot close the current extent prior to
moving to a new extent.

Digital Research : CP/M 3 Programmer’s Manual

Page 72

Error Code 05 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 06 is returned when byte 35, r2, of the referenced FCB is greater than 3.
Error Code 10 is returned if a media change occurs on the drive after the referenced FCB is activatedby a BDOS Open or Make Call.
Error Code 255 is returned if a physical error is encountered and the BDOS error mode is one of the
return modes (see Function 45). If the error mode is the default mode, a message identifying thephysical error is displayed at the console, and the calling program is terminated. When a physical error
is returned to the calling program, it is identified by register H as shown below:
01 Disk I/O error
02 Read-Only disk
03 Read-Only file04 Invalid drive error
On all error returns, except for physical errors, A = 255, the Write Random function sets register H to
the number of records successfully written 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 MultiSector Count is equal to one.

BDOS FUNCTION 35: COMPUTE FILE SIZE
Entry Parameters:
Registers C: 23H
DE: FCB Address

Returned Value:
Registers A: Error Flag
H: Physical or Extended error

Description:
The Compute File Size function determines the virtual file size, which is, in effect, the address of therecord immediately following the end of the file. The virtual size of a file corresponds to the physicalsize if the file is written sequentially. If the file is written in random mode, gaps might exist in the
allocation, and the file might contain fewer records than the indicated size. For example, if a single
record with record number 262,143, the CP/M 3 maximum is written to a file using the Write Randomfunction, then the virtual size of the file is 262,144 records even though only 1 data block is actually
allocated.
To compute file size, the calling program passes in register pair DE the address of an FCB in random
mode format, bytes r0, r1 and r2 present. Note that the FCB must contain an unambiguous filename andfiletype. Function 35 sets the random record field of the FCB to the random record number + 1 of theDigital Research : CP/M 3 Programmer’s Manual

Page 73

last record in the file. If the r2 byte is set to 04, then the file contains the maximum record count262,144.
A program can append data to the end of an existing file by calling Function 35 to set the random record
position to the end of file, and then performing a sequence of random writes starting at the preset record
address.
Note: the BDOS does not require that the file be open to use Function 35. However, if the file has been
written to, it must be closed before calling Function 35. Otherwise, an incorrect file size might bereturned.
Upon return, Function 35 returns a zero in register A if the file specified by the referenced FCB isfound, or an 0FFH in register A if the file is not found. Register H is set to zero in both of these cases. If
a physical error is encountered, Function 35 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, Function 35 returns to the calling program with register A set
to 0FFH, and register H set to one of the following physical errors:
01
04

Disk I/O error
Invalid drive error

BDOS FUNCTION 36: SET RANDOM RECORD
Entry Parameters:
Registers C: 24H
DE: FCB Address

Returned Value:Random Record Field Set

Description:
The Set Random Record function returns the random record number of the next record to be accessedfrom a file that has been read or written sequentially to a particular point. This value is returned in the
random record field, bytes r0, r1, and r2, of the FCB addressed by the register pair DE. Function 36 canbe useful in two ways:
First, it is often necessary to initially read and scan a sequential file to extract the positions of various
key fields. As each key is encountered, Function 36 is called to compute the random record position forthe data corresponding to this key. If the data unit size is 128 bytes, the resulting record number minus
one is placed into a table with the key for later retrieval. After scanning the entire file and tabularizing
the keys and their record numbers, you can move directly to a particular record by performing a random
read using the corresponding random record number that you saved earlier. The scheme is easily
generalized when variable record lengths are involved, because the program need only store the bufferrelative byte position along with the key and record number to find the exact starting position of the
keyed data at a later time.
A second use of Function 36 occurs when switching from a sequential read or write over to random reador write. A file is sequentially accessed to a particular point in the file, then Function 36 is called to set

Digital Research : CP/M 3 Programmer’s Manual

Page 74

the record number, and subsequent random read and write operations continue from the next record in
the file.

BDOS FUNCTION 37: RESET DRIVE
Entry Parameters:
Registers C: 25H
DE: Drive Vector

Returned Value:
Register A: 00H

Description:
The Reset Drive function programmatically restores specified drives to the reset state. A reset drive is
not logged-in and is in Read-Write status. The passed parameter in register pair DE is a 16-bit vector ofdrives to be reset, where the least significant bit corresponds to the first drive A, and the high-order bit
corresponds to the sixteenth drive, labeled P. Bit values of 1 indicate that the specified drive is to bereset.

BDOS FUNCTION 38: ACCESS DRIVE
Entry Parameters:
Register C: 26H

Description:
This is an MP/M function that is not supported under CP/M 3. If called, the file system returns a zero In register
A indicating that the access request is successful.

BDOS FUNCTION 39: FREE DRIVE
Entry Parameters:
Register C: 27H

Description:
This is an MP/M function that is not supported under CP/M 3. If called, the file system returns a zero In
register A indicating that the free request is successful.

Digital Research : CP/M 3 Programmer’s Manual

Page 75

BDOS FUNCTION 40: WRITE RANDOM WITH ZERO FILL
Entry Parameters:
Registers C: 28H
DE: FCB address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
The Write Random With Zero Fill function is identical to the Write Random function (Function 34)
with the exception that a previously unallocated data block is filled with zeros before the record iswritten. If this function has been used to create a file, records accessed by a read random operation that
contain all zeros identify unwritten random record numbers. Unwritten random records in allocated data
blocks of files created using the Write Random function (Function 34) contain uninitialized data.

BDOS FUNCTION 41: TEST AND WRITE RECORD
Entry Parameters:
Registers C: 29H
DE: FCB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
The Test and Write Record function is an MP/M 11" function that is not supported under CP/M 3. If
called, Function 41 returns with register A set to 0FFH and register H set to zero.

BDOS FUNCTION 42: LOCK RECORD
Entry Parameters:
Registers C: 2AH
DE: FCB Address

Returned Value:
Register A: 00H

Digital Research : CP/M 3 Programmer’s Manual

Page 76

Description:
The Lock Record function is an MP/M II function that is supported under CP/M 3 only to provide
compatibility between CP/M 3 and MP/M. It is intended for use in situations where more than one
running program has Read-Write access to a common file. Because CP/M 3 is a single-user operating
system in which only one program can run at a time, this situation cannot occur. Thus, under CP/M 3,
Function 42 performs no action except to return the value 00H in register A indicating that the record
lock operation is successful.

BDOS FUNCTION 43: UNLOCK RECORD
Entry Parameters:
Registers C: 2BH
DE: FCB Address

Returned Value:
Register A: 00H

Description:
The Unlock Record function is an MP/M II function that is supported under CP/M 3 only to provide
compatibility between CP/M 3 and MP/M. It is intended for use in situations where more than one
running program has Read-Write access to a common file. Because CP/M 3 is a single-user operating
system in which only one program can run at a time, this situation cannot occur. Thus, under CP/M 3,
Function 43 performs no action except to return the value 00H in register A indicating that the recor dunlock operation is successful.

BDOS FUNCTION 44: SET MULTI-SECTOR COUNT
Entry Parameters:
Registers C: 2CH
E: Number of Sectors

Returned Value:
Register A: Return CodeDescription:
The Set Multi-Sector Count function provides logical record blocking under CP/M 3. It enables a
program to read and write from 1 to 128 records of 128 bytes at a time during subsequent BDOS Read
and Write functions.
Function 44 sets the Multi-Sector Count value for the calling program to the value passed in register E.
Once set, the specified Multi-Sector Count remains in effect until the calling program makes another Set

Digital Research : CP/M 3 Programmer’s Manual

Page 77

Multi-Sector Count function call and changes the value. Note that the CCP sets the Multi-Sector Countto one when it initiates a transient program.
The Multi-Sector Count affects BDOS error reporting for the BDOS Read and Write functions. If anerror interrupts these functions when the Multi-Sector is greater than one, they return the number ofrecords successfully read or written in register H for all errors except for physical errors (A = 255).
Upon return, register A is set to zero if the specified value is in the range of 1 to 128. Otherwise, register
A is set to 0FFH.

BDOS FUNCTION 45: SET BDOS ERROR MODE
Entry Parameters:
Registers C: 2DH
E: BDOS Error Mode

Returned Value:
None

Description:
Function 45 sets the BDOS error mode for the calling program to the mode specified in register E. If
register E is set to 0FFH, 255 decimal, the error mode is set to Return Error mode. If register E is set to
0FEH, 254 decimal, the error mode is set to Return and Display mode. If register E is set to any othervalue, the error mode is set to the default mode.
The SET BDOS Error Mode function determines how physical and extended errors (see Section 2.2.13)
are handled for a program. The Error Mode can exist in three modes: the default mode, Return Error
mode, and Return and Display Error mode.
In the default mode, the BDOS displays a system message at the console that identifies the error andterminates the calling program. In the return modes, the BDOS sets register A to 0FFH, 255 decimal,
places an error code that identifies the physical or extended error in register H and returns to the calling
program. In Return and Display mode, the BDOS displays the system message before returning to thecalling program. No system messages are displayed, however, when the BDOS is in Return Error mode.

BDOS FUNCTION 46: GET DISK FREE SPACE
Entry Parameters:
Registers C: 2EH
E: Drive

Returned Value:First 3 bytes of current DMA buffer

Digital Research : CP/M 3 Programmer’s Manual

Page 78

Registers A: Error Flag
H: Physical Error

Description:
The Get Disk Free Space function determines the number of free sectors, 128 byte records, on thespecified drive. The calling program passes the drive number in register E, with 0 for drive A, 1 for B,
and so on, through 15 for drive P in a full 16-drive system. Function 46 returns a binary number in thefirst 3 bytes of the current DMA buffer. This number is returned in the following format: fs0 fs1 fs2
Disk Free Space Field Format
fs0 = low byte
fs1 = middle byte
fs2 = high byte
Note that the returned free space value might be inaccurate if the drive has been marked Read-Only.
Upon return, register A is set to zero if the function is successful. However, if the BDOS Error Mode isone of the return modes (see Function 45), and a physical error is encountered, register A is set to 0FFH,
255 decimal, and register H is set to one of the following values:
01 Disk I/O error
04 Invalid drive error

BDOS FUNCTION 47: CHAIN TO PROGRAM
Entry Parameters:
Registers C: 2FH
E: Chain Flag

Description:
The Chain To Program function provides a means of chaining from one program to the next without
operator intervention. The calling program must place a command line terminated by a null byte, 0FH,
in the default DMA buffer. If register E is set to 0FFH, the CCP initializes the default drive and user
number to the current program values when it passes control to the specified transient program.
Otherwise, these parameters are set to the default CCP values. Note that Function 108, Get/Set Program
Return Code, can be used to pass a two byte value to the chained program.
Function 47 does not return any values to the calling program and any encountered errors are handled
by the CCP.

BDOS FUNCTION 48: FLUSH BUFFERS
Entry Parameters:

Digital Research : CP/M 3 Programmer’s Manual

Page 79

Registers C: 30H

Returned Value:
E: Purge Flag
Registers A: Error Flag
H: Physical Error

Description:
The Flush Buffers function forces the write of any write-pending records contained in internal blocking/Deblocking buffers. If register E is set to 0FFH, this function also purges all active data buffers. Programs thatprovide write with read verify support need to purge internal buffers to ensure that verifying reads actuallyaccess the disk instead of returning data that is resident in internal data buffers. The CP/M 3 PIP utility is an
example of such a program.
Upon return, register A is set to zero if the flush operation is successful. If a physical error is encountered, theFlush Buffers 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 thecalling program is terminated. Otherwise, the Flush Buffers function returns to the calling program with register
A set to 0FFH and register H set to the following physical error code:
01
02
04

Disk I/O error
Read/only disk
Invalid drive error

BDOS FUNCTION 49: GET / SET SYSTEM CONTROLBLOCK
Entry Parameters:
Registers C: 31H
DE: SCB PB Address

Returned Value:
Registers A: Returned Byte
HL: Returned Word

Description:
Function 49 allows access to parameters located in the CP/M 3 System Control Block (SCB). The SCB
is a 100-byte data structure residing within the BDOS that contains flags and data used by the BDOS,CCP and other system components. Note that Function 49 is a CP/M 3 specific function. Programs
intended for both MP/M 11 and CP/M 3 should either avoid the use of this function or isolate calls tothis function in CP/M 3 version-dependent sections.
To use Function 49, the calling program passes the address of a data structure called the SCB parameter
block in register pair DE. This data structure identifies the byte or word of the SCB to be updated or
returned. The SCB parameter block is defined as:
SCBPB:DB OFFSET
DB SET; Offset within SCB; 0FFH if setting a byte

Digital Research : CP/M 3 Programmer’s Manual

Page 80; 0FEH if setting a word
; 001H - 0FDH are reserved; 000H if a get operation; Byte or word value to be set

DW VALUE

The OFFSET parameter identifies the offset of the field within the SCB to be updated or accessed. The
SET parameter determines whether Function 49 is to set a byte or word value in the SCB or if it is toreturn a byte from the SCB. The VALUE parameter is used only in set calls. In addition, only the first
byte of VALUE is referenced in set byte calls.
Use caution when you set SCB fields. Some of these parameters reflect the current state of the operating
system. If they are set to invalid values, software errors can result. In general, do not use Function 49 to
set a system parameter if another BDOS function can achieve the same result. For example, Function 49
can be called to update the Current DMA Address field within the SCB. This is not equivalent tomaking a Function 26, Set DMA Address call, and updating the SCB Current DMA field in this way
would result in system errors. However, you can use Function 49 to return the Current DMA address.
The System Control Block is summarized in the following table. Each of these fields is documented indetail in Appendix A.
Table 3-4. System Control Block
OffsetDescription

00 - 04 Reserved For System Use05

BDOS version number

06 - 09 User Flags
0A - 0f Reserved For System Use
10 - 11 Program Error return code
12 - 19 Reserved For System Use
1A

Console Width (columns)

1B

Console Column Position

1C

Console Page Length

1D -21 Reserved For System Use
22 -23

CONIN Redirection flag

24 - 25 CONOUT Redirection flag
26 - 27 AUXIN Redirection flag
28 - 29 AUXOUT Redirection flag
2A - 2B LSTOUT Redirection flag
2C

Page Mode

2D

Reserved For System Use

2E

CTRL-H Active

2F

Rubout Active

Digital Research : CP/M 3 Programmer’s Manual

Page 8130 - 32 Reserved For System Use
33 - 34 Console Mode
35 - 36 Reserved For System Use
37

Output Delimiter

38

List Output Flag

39 - 3B Reserved For System Use
3C-3D Current DMA Address
3E

Current Disk

3F - 43 Reserved For System Use
44

Current User Number

45 - 49 Reserved For System Use
4A

BDOS Multi-Sector Count

4B

BDOS Error Mode

4C - 4F Drive Search Chain (DISKS A:,E:,F:)50

Temporary File Drive

51

Error Disk

52 - 56 Reserved For System Use
57

BDOS flags

58 - 5C Date Stamp
5D - 5E Common Memory Base Address
5F - 63 Reserved For System Use
If Function 49 is called with the OFFSET parameter of the SCB parameter block greater than 63H, thefunction performs no action but returns with registers A and HL set to zero.

BDOS FUNCTION 50: DIRECT BIOS CALLS
Entry Parameters:
Registers C: 32H
DE: BIOS PB Address

Returned Value:
BIOS RETURN

Description:

Digital Research : CP/M 3 Programmer’s Manual

Page 82

Function 50 provides a direct BIOS call through the BDOS to the BIOS. The calling program passes theaddress of a data structure called the BIOS Parameter Block (BIOSPB) in register pair DE. The
BIOSPB contains the BIOS function number and register contents as shown below:
BIOSPB: db FUNC
db AREGdw BCREG
dw DEREG
dw HLREG; BIOS function no.
; A register contents; BC register contents; DE register contents; HL register contents

System Reset (Function 0) is equivalent to Function 50 with a BIOS function number of 1.
Note that the register pair BIOSPB fields (BCREG, DEREG, HLREG) arc defined in low byte, highbyte order. For example, in the BCREG field, the first byte contains the C register value, the second
byte contains the B register value.
Under CP/M 3, direct BIOS calls via the BIOS jump vector are only supported for the BIOS Console
I/O and List functions. You must use Function 50 to call any other BIOS functions. In addition,
Function 50 intercepts BIOS Function 27 (Select Memory) calls and returns with register A set to zero.
Refer to the CP/M Plus (CP/M Version 3) Operating System System Guide for the definition of theBIOS functions and their register passing and return conventions.

BDOS FUNCTION 59: LOAD OVERLAY
Entry Parameters:
Registers C: 3BH
DE: FCB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
Only transient programs with an RSX header can use the Load Overlay function because BDOS
Function 59 is supported by the LOADER module. The calling program must have a header to force the
LOADER to remain resident after the program is loaded (see Section 1.3).
Function 59 loads either an absolute or relocatable module. Relocatable modules are identified by afiletype of PRL. Function 59 does not call the loaded module. The referenced FCB must be successfully
opened before Function 59 is called. The load address is specified in the first two random record bytesof the FCB, r0 and r1. The LOADER returns an error if the load address is less than 100H, or if
performing the requested load operation would overlay the LOADER, or any other Resident System
Extensions that have been previously loaded.
When loading relocatable files, the LOADER requires enough room at the load address for the complete
PRL file including the header and bit map (see Appendix B). Otherwise an error is returned. Function
59 also returns an error on PRL file load requests if the specified load address is not on a page
boundary.

Digital Research : CP/M 3 Programmer’s Manual

Page 83

Upon return, Function 59 sets register A to zero if the load operation is successful. If the LOADER RSX
is not resident in memory because the calling program did not have a RSX header, the BDOS returns
with register A set to 0FFH and register H set to zero. If the LOADER detects an invalid load address,
or if insufficient memory is available to load the overlay, Function 59 returns with register A set to
0FEH. All other error returns are consistent with the error codes returned by BDOS Function 20, Read
Sequential.

BDOS FUNCTION 60: CALL RESIDENT SYSTEM EXTENSION
Entry Parameters:
Registers C: 3CH
DE: RSX PB Address

Returned Value:
Registers A: Error Code
H: Physical Error

Description:
Function 60 is a special BDOS function that you use when you call Resident System Extensions. The
RSX subfunction is specified in a structure called the RSX Parameter Block, defined as follows:
RSXPB: db FUNC
db NUMPARMS
dw PARMETER1
dw PARMETER2
dw PARMETERN; RSX Function number; Number of word Parameters; Parameter I; Parameter 2; Parameter n

RSX modules filter all BDOS calls and capture RSX function calls that they can handle. If there is no
RSX module present in memory that can handle a specific RSX function call, the call is not trapped, andthe BDOS returns 0FFH in registers A and L. RSX function numbers from 0 to 127 are available for
CP/M 3 compatible software use. RSX function numbers 128 to 255 are reserved for system use.

BDOS FUNCTION 98: FREE BLOCKS
Entry Parameters:
Register C: 62H

Returned Value:
Registers A: Error Flag
H: Physical Error

Description:

Digital Research : CP/M 3 Programmer’s Manual

Page 84

The Free Blocks function scans all the currently logged-in drives, and for each drive returns to freespace all temporarily-allocated data blocks. A temporarily-allocated data block is a block that has been
allocated to a file by a BDOS write operation but has not been permanently recorded in the directory by
a BDOS close operation. The CCP calls Function 98 when it receives control following a system warm
start. Be sure to close your file, particularly any file you have written to, prior to calling Function 98.
In the non-banked version of CP/M 3, Function 98 frees only temporarily allocated blocks for systems
that request double allocation vectors in GENCPM.
Upon return, register A is set to zero if Function 98 is successful. If a physical error is encountered, theFree Blocks 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 theconsole and the calling program is terminated. Otherwise, the Free Blocks function returns to the calling
program with register A set to 0FFH and register H set to the following physical error code:
04 Invalid drive error

BDOS FUNCTION 99: TRUNCATE FILE
Entry Parameters:
Registers C: 63H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Extended or Physical Error

Description:
The Truncate File function sets the last record of a file to the random record number contained in thereferenced FCB. 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 bytes 33
through 35, r0, r1, and r2, specifying the last record number of the file. The last record number is a 24
bit value, stored with the least significant byte first, r0, the middle byte next, r1, and the high byte last,r2. This value can range from 0 to 262,143, which corresponds to a maximum value of 3 in byte r2.
If the file specified by the referenced FCB 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). Function 99 requires that the file specified by the FCB not be open,
particularly if the file has been written to. In addition, any activated FCBs naming the file are not valid
after Function 99 is called. Close your file before calling Function 99, and then reopen it after the call tocontinue processing on the file.
Function 99 also requires that the random record number field of the referenced FCB specify a valueless than the current file size. In addition, if the file is sparse, the random record field must specify arecord in a region of the file where data exists.
Upon return, the Truncate function returns a Directory Code in register A with the value 0 if the
Truncate function is successful, or 0FFH, 255 decimal, if the file is not found or the record number isinvalid. Register H is set to zero in both of these cases. If a physical or extended error is encountered,Digital Research : CP/M 3 Programmer’s Manual

Page 85

the Truncate 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 theconsole and the program is terminated. Otherwise, the Truncate function returns to the calling programwith 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 file04 Invalid drive error
07 File password error
09 ? in filename or filetype field

BDOS FUNCTION 100: SET DIRECTORY LABEL
Entry Parameters:
Registers C:64H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical or Extended Error

Description:
The Set Directory Label function creates a directory label, or updates the existing directory label for the
specified drive. The calling program passes in register pair DE the address of an FCB containing thename, type, and extent fields to be assigned to the directory label. The name and type fields of thereferenced FCB are not used to locate the directory label in the directory; they are simply copied into the
updated or created directory label. The extent field of the FCB, byte 12, contains the user's specificationof the directory label data byte. The definition of the directory label data byte is:
bit 7

Require passwords for password-protected files(Not supported in non-banked CP/M 3 systems)

6

Perform access date and time stamping

5

Perform update date and time stamping

4

Perform create date and time stamping0

Assign a new password to the directory label

If the current directory label is password protected, the correct password must be placed in the first eightbytes of the current DMA, or have been previously established as the default password (see Function
106). If bit 0, the low-order bit, of byte 12 of the FCB is set to 1, it indicates that a new password for the
directory label has been placed in the second eight bytes of the current DMA.

Digital Research : CP/M 3 Programmer’s Manual

Page 86

Note that Function 100 is implemented as an RSX, DIRLBL.RSX, in non-banked CP/M 3 systems. If
Function 100 is called in non-banked systems when the DIRLBL.RSX is not resident an error code of
0FFH is returned.
Function 100 also requires that the referenced directory contain SFCBs to activate date and timestamping on the drive. If an attempt is made to activate date and time stamping when no SFCBs exist,
Function 100 returns an error code of 0FFH in register A and performs no action. The CP/M 3 INITDIR
utility initializes a directory for date and time stamping by placing an SFCB record in every fourth entryof the directory.
Function 100 returns a Directory Code in register A with the value 0 if the directory label create or
update is successful, or 0FFH, 255 decimal, if no space exists in the referenced directory to create a
directory label, or if date and time stamping was requested and the referenced directory did not contain
SFCBS. Register H is set to zero in both of these cases. If a physical error or extended error isencountered,
Function 100 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 andthe calling program is terminated. Otherwise,
Function 100 returns to the calling program with register A set to 0FFH and register H set to one of thefollowing physical or extended error codes:
01 Disk I/O error
02 Read-Only disk
04 Invalid drive error
07 File password error

BDOS FUNCTION 101: RETURN DIRECTORY LABEL DATA
Entry Parameters:
Registers C: 65H
E: Drive

Returned Value:
Registers A: Directory Label
Data Byte
H: Physical Error

Description:
The Return Directory Label Data function returns the data byte of the directory label for the specified
drive. The calling program passes the drive number in register E with 0 for drive A, 1 for drive B, andso on through 15 for drive P in a full sixteen drive system. The format of the directory label data byte isshown below:
bit 7 Require passwords for password protected files

Digital Research : CP/M 3 Programmer’s Manual
6

Perform access date and time stamping

5

Perform update date and time stamping

4

Perform create date and time stamping0

Directory label exists on drive

Page 87

Function 101 returns the directory label data byte to the calling program in register A. Register A equal
to zero indicates that no directory label exists on the specified drive. If a physical error is encounteredby Function 101 when the BDOS Error mode is in one of the return modes (see Function 45), thisfunction returns with register A set to 0FFH, 255 decimal, and register H set to one of the following:
01 Disk I/O error
04 Invalid drive error

BDOS FUNCTION 102: READ FILE DATE STAMPS ANDPASSWORD MODE
Entry Parameters:
Registers C: 66H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical Error

Description:
Function 102 returns the date and time stamp information and password mode for the specified file inbyte 12 and bytes 24 through 32 of the specified FCB. The calling program passes in register pair DE,
the address of an FCB in which the drive, filename, and filetype fields have been defined.
If Function 102 is successful, it sets the following fields in the referenced FCB:

byte 12

Password mode field. Byte 12 equal to zero indicates the file has not been
assigned a password. In non-banked systems, byte 12 is always set to
zero.

bit 7

Read mode

bit 6

Write mode

bit 4

Delete mode

byte 24-27 Create or Access time stamp field
byte 28-31 Update time stamp fieldDigital Research : CP/M 3 Programmer’s Manual

Page 88

The date stamp fields are set to binary zeros if a stamp has not been made. The format of the time stamp
fields is the same as the format of the date and time structure described in Function 104.
Upon return, Function 102 returns a Directory Code in register A with the value zero if the function is
successful, or 0FFH, 255 decimal, if the specified file is not found. Register H is set to zero in both ofthese cases. If a physical or extended error is encountered, Function 102 performs different actions
depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, amessage identifying the error is displayed at the console and the calling program is terminated.
Otherwise, Function 102 returns to the calling program with register A set to 0FFH and register H set toone of the following physical or extended error codes:
01 Disk I/O error
04 Invalid drive error
09 ? in filename or filetype field

BDOS FUNCTION 103: WRITE FILE XFCB
Entry Parameters:
Registers C: 67H
DE: FCB Address

Returned Value:
Registers A: Directory Code
H: Physical Error

Description:
Write File XFCB function creates a new XFCB or updates the existing XFCB for the specified file. The
calling program passes in register pair DE the address of an FCB in which the drive, name, type, andextent fields have been defined. The extent field specifies the password mode and whether a new
password is to be assigned to the file. The format of the extent byte is shown below:
FCB byte 12 (ex)XFCB password mode

bit 7

Read mode

bit 6

Write mode

bit 5

Delete mode

bit 0

Assign new password to the file

If the specified file is currently password protected, the correct password must reside in the first eightbytes of the current DMA, or have been previously established as the default password (see Function
106). If bit 0 is set to 1, the new password must reside in the second eight bytes of the current DMA.
Upon return, Function 103 returns a Directory Code in register A with the value zero if the XFCB create
or update is successful, or 0FFH, 255 decimal, if no directory label exists on the specified drive, or the
file named in the FCB is not found, or no space exists in the directory to create an XFCB. Function 103

Digital Research : CP/M 3 Programmer’s Manual

Page 89

also returns with 0FFH in register A if passwords are not enabled by the referenced directory's label. On
non-banked systems, this function always returns with register A = 0FFH because passwords are notsupported. Register H is set to zero in all of these cases. If a physical or extended error is encountered,
Function 103 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 andthe calling program is terminated. Otherwise, Function 103 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
07 File password error
09 ? in filename or filetype field

BDOS FUNCTION 104: SET DATE AND TIME
Entry Parameters:
Registers C: 68H
DE: DAT Address

Returned Value:none

Description:
The Set Date and Time function sets the system internal date and time. The calling program passes theaddress of a 4-byte structure containing the date and time specification in the register pair DE. The
format of the date and time (DAT) data structure is:byte 0 - 1 Date field
byte 2

Hour field

byte 3

Minute field

The date is represented as a 16-bit integer with day 1 corresponding to January 1, 1978. The time isrepresented as two bytes: hours and minutes are stored as two BCD digits.
This function also sets the seconds field of the system date and time to zero.

BDOS FUNCTION 105: GET DATE AND TIME
Entry Parameters:
Registers C: 69H

Digital Research : CP/M 3 Programmer’s Manual

Page 90

DE: DAT Address

Returned Value:
Register A: seconds
DAT setDescription:
The Get Date and Time function obtains the system internal date and time. The calling program passes
in register pair DE, the address of a 4-byte data structure which receives the date and time values. The
format of the date and time, DAT, data structure is the same as the format described in Function 104.
Function 105 also returns the seconds field of the system date and time in register A as a two digit BCD
value.

BDOS FUNCTION 106: SET DEFAULT PASSWORD
Entry Parameters:
Registers C: 6AH
DE: Password Address

Returned Value:none

Description:
The Set Default Password function allows a program to specify a password value before a file protectedby the password is accessed. When the file system accesses a password-protected file, it checks thecurrent DMA, and the default password for the correct value. If either value matches the file's password,
full access to the file is allowed. Note that this function performs no action in non-banked CP/M 3
systems because file passwords are not supported.
To make a Function 106 call, the calling program sets register pair DE to the address of an 8-byte fieldcontaining the password.

BDOS FUNCTION 107: RETURN SERIAL NUMBER
Entry Parameters:
Registers C: 6BH
DE: Serial Number Field

Returned Value:
Serial number field set

Digital Research : CP/M 3 Programmer’s Manual

Page 91

Description:
Function 107 returns the CP/M 3 serial number to the 6-byte field addressed by register pair DE.

BDOS FUNCTION 108: GET/SET PROGRAM RETURN CODE
Entry Parameters:
Registers C: 6CH
DE: 0FFFFH (Get) or Program Return Code (Set)

Returned Value:
Register HL: Program Return Code or (no value)

Description:
CP/M 3 allows programs to set a return code before terminating. This provides a mechanism forprograms to pass an error code or value to a following job step in batch environments. For example,
Program Return Codes are used by the CCP in CP/M 3's conditional command line batch facility.
Conditional command lines are command lines that begin with a colon, :. The execution of a conditionalcommand depends on the successful execution of the preceding command. The CCP tests the returncode of a terminating program to determine whether it successfully completed or terminated in error.
Program return codes can also be used by programs to pass an error code or value to a chained program(see Function 47, Chain To Program).
A program can set or interrogate the Program Return Code by calling Function 108. If register pair DE= 0FFFFH, then the current Program Return Code is returned in register pair HL. Otherwise, Function
108 sets the Program Return Code to the value contained in register pair DE. Program Return Codes aredefined in Table 3-5.
Table 3-5. Program Return Codes
CodeMeaning0000-FEFF

Successful returnFF00-FFFE

Unsuccessful return0000
FF80-FFFC

The CCP initializes the Program Return Code to zero unless the program
is loaded as the result of program chain.
Reserved

FFFD

The program is terminated because of a fatal BDOS error.

FFFE

The program is terminated by the BDOS because the user typed a CTRLC.

BDOS FUNCTION 109: GET/SET CONSOLE MODE
Entry Parameters:

Digital Research : CP/M 3 Programmer’s Manual

Page 92

Registers C: 6DH
DE: 0FFFFH (Get) or Console Mode (Set)

Returned Value:
Register HL: Console Mode or (no value)

Description:
A program can set or interrogate the Console Mode by calling Function 109. If register pair DE =0FFFFH, then the current Console Mode is returned in register HL. Otherwise, Function 109 sets theConsole Mode to the value contained in register pair DE.
The Console Mode is a 16-bit system parameter that determines the action of certain BDOS Console I/Ofunctions. The definition of the Console Mode is:

Bits 8 & 9

bit 0 = 1

CTRL-C only status for Function 1 1.

bit 0 = 0

Normal status for Function 1 1.

bit 1 = 1

Disable stop scroll, CTRL-S, start scroll, CTRL-Q, support.

bit 1 = 0

Enable stop scroll, start scroll support.

bit 2 = 1

Raw console output mode. Disables tab expansion for
Functions 2, 9 and 111. Also disables printer echo, CTRL-P,
support.

bit 2 = 0

Normal console output mode.

bit 3 = 1

Disable CTRL-C program termination

bit 3 = 0

Enable CTRL-C program termination
Meaning

bit 8 = 0, bit 9 = 0 conditional status
bit 8 = 0, bit 9 = 1 false status
bit 8 = 1, bit 9 = 0 true status

Console status mode for RSXs that perform console input
redirection from a file. These bits determine how the RSX
responds to console status requests.

bit 8 = 1, bit 9 = 1 bypass redirection
Note that the Console Mode bits are numbered from right to left.
The CCP initializes the Console Mode to zero when it loads a program unless the program has an RSX
that overrides the default value. Refer to Section 2.2.1 for detailed information on Console Mode.

BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER
Entry Parameters:

Digital Research : CP/M 3 Programmer’s Manual

Page 93

Registers C: 6EH
DE: 0FFFFH (Get) or
E: Output Delimiter (Set)

Returned Value:
Register A: Output Delimiter or (no value)

Description:
A program can set or interrogate the current Output Delimiter by calling Function 110. If register pair
DE = 0FFFFH, then the current Output Delimiter is returned in register A. Otherwise, Function 110 sets
the Output Delimiter to the value contained in register E.
Function 110 sets the string delimiter for Function 9, Print String. The default delimiter value is a dollar
sign, $. The CCP restores the Output Delimiter to the default value when a transient program is loaded.

BDOS FUNCTION 111: PRINT BLOCK
Entry Parameters:
Registers C: 6FH
DE: CCB Address

Returned Value:none

Description:
The Print Block function sends the character string located by the Character Control Block, CCB,
addressed in register pair DE, to the logical console, CONOUT:. If the Console Mode is in the default
state (see Section 2.2.1), Function 111 expands tab characters, CTRL-I, in columns of eight 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.
The CCB format is:byte 0 - 1 Address of character string (word value)
byte 2 - 3 Length of character string (word value)

BDOS FUNCTION 112: LIST BLOCK
Entry Parameters:
Registers C: 70H
DE: CCB Address

Returned Value:

Digital Research : CP/M 3 Programmer’s Manual

Page 94

none

Description:
The List Block function sends the character string located by the Character Control Block, CCB,
addressed in register pair DE, to the logical list device, LST.-.
The CCB format is:byte 0-1 Address of character string (word value)
byte 2-3 Length of character string (word value)

BDOS FUNCTION 152: PARSE FILENAME
Entry Parameters:
Registers C: 98H
DE: PFCB Address

Returned Value:
Register HL: Return code
Parsed file control block

Description:
The Parse Filename function parses an ASCII file specification and prepares a File Control Block, FCB.
The calling program passes the address of a data structure called the Parse Filename Control Block,
PFCB, in register pair DE. The PFCB contains the address of the input ASCII filename string followedby the address of the target FCB as shown below:
PFCB: DW INPUTDW FCB; Address of input ASCII string; Address of target FCB

The maximum length of the input ASCII string to be parsed is 128 bytes. The target FCB must be 36
bytes in length.
Function 152 assumes the input string contains file specifications in the following form:{d:}filename{.typ}{;password}

where items enclosed in curly brackets are optional. Function 152 also accepts isolated drive
specifications d: in the input string. When it encounters one, it sets the filename, filetype, and password
fields in the FCB to blank.
The Parse Filename function parses the first file specification it finds in the input string. The function
first eliminates leading blanks and tabs. The function then assumes that the file specification ends on thefirst delimiter it encounters that is out of context with the specific field it is parsing. For instance, if it
finds a colon, and it is not the second character of the file specification, the colon delimits the entire filespecification.
Function 152 recognizes the following characters as delimiters:

Digital Research : CP/M 3 Programmer’s Manual‘‘
CTRL-I
CTRL-M
;
=
<
>
.
:
,
|
[
]

Page 95

spacetab
return(semicolon) - except before password field(equal)(less than)(greater than)(period) - except after filename and before filetype(colon) - except before filename and after drive(comma)(vertical bar)(left square bracket)(right square bracket)

If Function 152 encounters a non-graphic character in the range 1 through 31 not listed above, it treats
the character as an error. The Parse Filename function initializes the specified FCB shown in Table 3 -6.
Table 3-6. FCB Format
LocationContents

byte 0The drive field is set to the specified drive. If the drive is not specified, the default drive code isused. 0 = default, 1 = A, 2 = B.
The name is set to the specified filename. All letters are converted to upper-case. If the name is
not eight characters long, the remaining bytes in the filename field are padded with blanks.

byte 1-8
If the filename has an asterisk,, *, all remaining bytes in the filename field are filled in withquestion marks, ?. An error occurs if the filename is more than eight bytes long. byte

byte 9-11

The type is set to the specified filetype. If no filetype is specified, the type field is initialized toblanks. All letters are converted to upper-case. If the type is not three characters long, theremaining bytes in the filetype field are padded with blanks.
If an asterisk, *, occurs, all remaining bytes are filled in with question marks, ?. An error occurs
if the type field is more than three bytes long.

byte 12-15

Filled in with zeros.

byte 16-23

The password field is set to the specified password. If no password is specified, it is initialized
to blanks. If the password is less than eight characters long, remaining bytes are padded withblanks. All letters are converted to upper-case. If the password field is more than eight bytes
long, an error occurs. Note that a blank in the first position of the password field implies nopassword was specified.

byte 24-31

Reserved for system use.

If an error occurs, Function 152 returns an 0FFFFH in register pair HL.
On a successful parse, the Parse Filename function checks the next item in the input string. It skips overtrailing blanks and tabs and looks at the next character. If the character is a null or carriage return, it
returns a 0 indicating the end of the input string. If the character is a delimiter, it returns the address ofthe delimiter. If the character is not a delimiter, it returns the address of the first trailing blank or tab.

Digital Research : CP/M 3 Programmer’s Manual

Page 96

If the first non-blank or non-tab character in the input string is a null, 0, or carriage return, the Parse
Filename function returns a zero indicating the end of string.
If the Parse Filename function is to be used to parse a subsequent file specification in the input string,
the returned address must be advanced over the delimiter before placing it in the PFCB.

Digital Research : CP/M 3 Programmer’s Manual

Page 97

Section 4 : Programming Examples
The programs presented in this section illustrate how to use the BDOS functions described in the previous
section. The examples show how to copy a file, how to dump a file, how to create or access a random accessfile, and how to write an RSX program.

4.1 A Sample File-To-File Copy Program
The following program illustrates simple file operations. You can create the program source file, COPY.ASM,
using ED or another editor, and then assemble COPY.ASM using MAC. MAC produces the file COPY.HEX.
Use the utility HEXCOM to produce a COPY.COM file that can execute under CP/M 3. The COPY program
first sets the stack pointer to a local area, then moves the second name from the default area at 006CH to a 33 byte file control block named DFCB. The DFCB is then prepared for file operations by clearing the current
record field. Because the CCP sets up the source FCB at 005CH upon entry to the COPY program, the sourceand destination FCBs are now ready for processing. To prepare the source FCB, the CCP places the first nameinto the default FCB, with the proper fields zeroed, including the current record field at 007CH.
COPY continues by opening the source file, deleting any existing destination file, and then creating thedestination file. If each of these operations is successful, the COPY program loops at the label COPY until eachrecord is read from the source file and placed into the destination file. Upon completion of the data transfer, thedestination file is closed, and the program returns to the CCP command level by lumping to BOOT.
; sample file-to-file copy program; at the ccp level , the command; copy a:x.y b:u.v; copies the file named x.y from drive; a to a file named u.v on drive b.
boot equ 0000h; system reboot
bdos equ 0005h; bdos entry point
fcb1 equ 005CH; first file namesfcb equ fcb1
; source fcb
fcb2 equ 00Bch; second file namedbuff equ 0080h; default buffer
tpa equ 0100h; beginning of tpa
printf equ 9; Print buffer func*
openf equ 15; Open file func*
closef equ 16; close file func*
deletef equ 19; delete file func*
readf equ 20; sequential read
writef equ 21; sequential write
makef equ 22; make file func*
org tpa; beginning of tpa
lxi sp,stack; local stack;; move second file name to dfcb
mvi c,16; half an fcb
lxi d,fcb2; source of movelxi h,dfcb; destination fcb
mfcb: ldax d; source fcb
inx d; ready next
m0v m,a; dest fcb
inx h; ready next
dcr c
; count l6...0
jnz mfcb; loop 16 times; name has been moved, zero cr
xra a; a = 00h
sta dfcbcr; current rec = 0; source and destination fcbs readyDigital Research : CP/M 3 Programmer’s Manuallxi d,sfcb
call 0pen
lxi d,nofile
inr acz finis; source file
; error if 255; ready message; 255 becomes 0; done if no file;; source file open, prep destination
lxi d ,dfcb; destination
call delete; remove if present
lxi d,dfcb; destination
call make; create the filelxi d,nodir; ready message
inr a; 255 becomes 0
cz finis; done if no dir space;; source file open, dest file open
; copy until end of file on source
copy: lxi d,sfcb; source
call read; read next record
ora a; end of file?
Jnz eofile; skip write if s0; not end of file, write the record
lxi d,dfcb; destination
call write; write record
lxi d,space; ready message
ora a; 00 if write ok
cnz finis; end if so
Jmp copy; loop until eof;eofile:; end of file, close destination
lxi d,dfcb; destination
call close; 255 if error
lxi h,wrprot; ready message
inr a; 255 becomes 00
cz finis; should not happen;; copy operation complete, end
lxi d,normal; ready message;
finis:; write message given by de, reboot
mvi c,printf
call bdos; write message
Jmp boot; reboot system; system interface subroutines; (all return directly from bdos)
open: mvi c ,openf
Jmp bdos
close: mvi c,closef
Jmp bdosdelete: mvi c ,deletef
Jmp bdos
read: mvi C ,readf
Jmp bdos
write: mvi c ,writef
Jmp bdos
make: mvi c,makef
Jmp bdos; console messages
nofile: db 'no source file$'
nodir: db 'no directory space$'
space: db 'out of data space$'
wrprot: db 'write protected?$'Page 98

Digital Research : CP/M 3 Programmer’s Manual
normal: db 'copy complete$'; data areas
dfcb: ds 33
0lfa = dfcbcr equ dfcb+32
ds 32
stack: 021b
end

Page 99; destination fcb; current record; 16 level stack

Note that this program makes several simplifications and could be enhanced. First, it does not check for invalid
filenames that could, for example, contain ambiguous references. This situation could be detected by scanningthe 32-byte default area starting at location 005CH for ASCII question marks. To check that the filenames have,in fact, been included, COPY could check locations 005DH and 006DH for nonblank ASCII characters.
Finally, a check should be made to ensure that the source and destination filenames are different. Speed could
be improved by buffering more data on each read operation. For example, you could determine the size ofmemory by fetching FBASE from location 0006H, and use the entire remaining portion of memory for a data
buffer. You could also use CP/M 3's Multi-Sector I/O facility to read and write data in up to 16K units.

4.2 A Sample File Dump Utility
The following dump program reads an input file specified in the CCP command line, and then displays thecontent of each record in hexadecimal format at the console.
DUMP Program reads input file and displays hex data
; DUMP program reads input file and displays hex data;
0100 org l00h
0005 = bd0s equ 0005h; bdos entry point
0001 = c0ns equ 1; read console
0002 = typef equ 2; type function
0009 = printf equ 9; buffer print entry
000b = brkf equ 11; break key functi0n (true if char
000f = openf equ 15; file open
0014 = readf equ 20; read function
005c = fcb equ Sch; file control block address
0080 = buff equ 80h; input disk buffer address; non graphic characters000d = cr equ 0dh; carriage return000a = lf equ 0ah; line feed
; file control block definitions
005c = fcbdn equ fcb+0; disk name005d = fcbfn equ fcb+1; file name0065 = fcbft equ fcb+B; disk file tyPe (3 characters)
0068 = fcbrl equ fcb+12; file's current reel number
00Gb = fcbrc equ fcb+15; file's record count (0 to 128)
007c = fcbcr equ fcb+32; current (next) record number (0007d = fcbln equ fcb+33; fcb length; set up stacklxi h,0dad sp; entry stack pointer in hi from the ccp
shld oldsp; set sp to local stack area (restored at finis)
lxi sp,stktop; read and Print successive buffers
call setup; set up input filecpi 255; 255 if file not present
jnz openok; skip if open is ok;; file not there, give error message and return

Digital Research : CP/M 3 Programmer’s Manual

Page 100lxi d,opnmsg
call err
jmp finis; to return
openok:; open operation ok, set buffer index to end
mvi a,80h
sta ibp; set buffer pointer to 80h; hl contains next address to print
lxi h,0; start with 0000
gloop:
push h; save line position
call gnb
pop h; recall line position
jc finis; carry set by gnb if end file
mov b,a; print hex values; check for line fold
mov a,lani 0fh; check low 4 bits
jnz nonum; print line number
call crlf; check for break key
call break; accum lsb = 1 if character readyrrc; into carryjc finis; do not print any more
mov a,hcall phex
mov a,lcall phex
nonum:
inx h; to next line number
mvi a,' 'call pchar
mov a,bcall phex
jmp gloop;
finis:; end of dump
call crlf
lhld oldsp
sphl; stack pointer contains ccp's stack location
ret; to the ccp; subroutines
break:;check break key (actually any key will do)
push h! push d! push b ; environment saved
mvi c,brkf
call bdos
pop b! pop d! pop h; environment restored
retpchar:; print a character
push h! push d! push b ; saved
mvi c,typef
mov e ,acall bdos
pop b! pop d! pop h; restored
ret
crlf:
mvi a,crcall pchar
mvi a,lf
call pchar
ret
pnib:
; print nibble in reg aani 0fh; low 4 bits
cpi 10jnc p10; less than or equal to 9
adi '0'
jmp prn; greater 0r equal t0 10

Digital Research : CP/M 3 Programmer’s Manual
pl0:
prn:

adi 'a' - 10
call pchar
ret

phex:

; Print hex char in reg apush psw
rrc
rrc
rrc
rrc
call pnib
pop pSW
call pnib
ret; print nibble

err:; Print error message; d,e addresses message ending With"$"mvi c,printf; print buffer functi0n
call bdos
retgnb; get next byte
lda ibpcPi 80h
jnz g0; read another buffer
call diskr
ora a; zero value if read ok
jz g0; for another byte
; end of data, return With carry Set for eof
stc
ret
g0:
; read the byte at buff+reg a
mov e,a; ls byte of buffer index
mvi d,0; double precision index to de
inr a; index=index+l
sta ibp; back to memory; Pointer is incremented; save the current file address
lxi h,buff
dad d; absolute character address is in hl
mov a,m; byte is in the accumulatorora a; reset carry bit
retsetup:; set up file
; open the file for input
xra a; zero to accum
sta fcbcr; clear current rec0rd
lxi d,fcb
mvi c,openf
call bdos; 255 in accum if open error
retdiskr:; read disk file record
Push h!Push d! Push b
lxi d,fcb
mvi c,readf
call bdos
Pop b! Pop d! Pop hret; fixed message area
signon: db 'file dumP version 2.0$'
opnmsg: db cr,lf ,'no input file Present on disk$'; variable area
ibp: ds 2; input buffer Pointeroldsp: ds 2
; entry sP value from ccP; stack area
ds 64
; reserve 32 level stackstktop:end

Page 101

Digital Research : CP/M 3 Programmer’s Manual

Page 102

4.3 A Sample Random Access ProgramThis example is an extensive but complete example of random access operation. The following program reads
or writes random records upon command from the terminal. When the program has been created, assembled,and placed into a file labeled RANDOM.COM, the CCP level command A>RANDOM X.DAT can start thetest program. In this case, the RANDOM program looks for a file X.DAT and, if it finds it, prompts the console
for input. If X.DAT is not found, RANDOM creates the file before displaying the prompt. Each prompt takes
the form:
next command?
and is followed by operator input, terminated by a carriage return. The input commands take the form:
nW nR nF Q
where n is an integer value in the range 0 to 262143, and W, R, F, and Q are simple command characterscorresponding to random write, W, random read, R, random write with zero fill, F, and quit processing, Q. If
you enter a W or F command, the RANDOM program issues the prompt:
type data:
You then respond by typing up to 127 characters, followed by a carriage return. RANDOM then writes thecharacter string into the X.DAT file at record n. If you enter an F command, the RANDOM program fills
previously unallocated data blocks with zeros before writing record n. If you enter the R command, RANDOM
reads record number n and displays the string value at the console. If you enter the Q command, the X.DAT fileis closed, and the program returns to the console command processor. In the interest of brevity, the only error
message is:Err, try again
The program begins with an initialization section where the input file is opened or created, followed by acontinuous loop at the label ready where the individual commands are interpreted. The program uses the default
file control block at 005CH and the default buffer at 0080H in all disk operations. The utility subroutines that
follow contain the principal input line processor, called readc. This particular program shows the elements ofrandom access processing and can be used as the basis for further program development.
;*** *;* *;* sample random access Program for CP/M 3*;* *;*** *
0100 org l00h
; base of tpa
0000 = reboot equ 0000h; system reboot
0005 = bdos equ 0005h; bdos entry Point
0001 - coninp equ 1; console input function
0002 - conout equ 2; console outPut function
0009 - pstring equ 9; Print string until '$'000a = rstring equ 10; read console buffer000c - version equ 12; return version number
000f = openf equ 15; file open function
0010 - closef equ 16; close function
0016 - makef equ 22; make file function
0021 - readr equ 33; read random
0022 - Writer equ 34; write random
0028 - Wrtrzf equ 40; Write random zero fillDigital Research : CP/M 3 Programmer’s Manual
0098 - parsef equ 152; parse function
005c - fcb equ 00Sch; default file control block
007D - ranrec equ fcb+33; random record Position
007F = ran0vf equ fcb+35; high order (overflow) byte
0080 = buff equ 0080h; buffer address
000D = or equ 0dh; carriage return000a = 1f equ 0ah; line feed
;***
;* *
;* load SP, Set-up file for random access *
;* *
;***
lxi sp,stack; version 3.1?
mvi c,version
call bdos
cp 31h; version 3.1 or better?
jnc versok; bad version, message and go backlxi d,badver
call Print
jmp reboot
versok :; correct version for random access
mvi c,openf; open default fcb
rdname: lda fcb+1
cPi ' '
jnz opfile
lxi d,entmsg
call Print
call ParsejmP rdname
opfile: lxi d,fcb
call bdos
inr a; err 255 becomes zerojnz ready; cannot open file, so create it
mvi c,makef
lxi d,fcb
call bdos
inr a; err 255 becomes zerojnz ready; cannot create file, directory fulllxi d,nospacecall print
jmp reboot; back to ccP
; ***
;* *
;* loop back to "ready" after each command *
;* *
;***
ready:; file is ready for processing
call readcom; read next command
shld ranrec; store input record*lxi h,ran0vf
mov m,c; set ranrec high byte
cpi 'Q'; quit?
jnz notq; quit processing,close file :mvi c,closef
lxi d,fcb
call bdos
inr a; err 255 becomes 0
jz error; error message ' retry
jmp reboot; back to ccP;;***;* end of quit command, pr0cess write *
;* *
;***

Page 103

Digital Research : CP/M 3 Programmer’s Manual
notq:

Page 104; not the quit command, random Write?
cpi 'W'jnz notw; this is a random Write, fill buffer until cr
lxi d,datmsg
call Print;data Prompt
mvi c,127; UP to 127 characterslxi h,buff; destination
rloop:; read next character to buff
push b; save counter
push h; next destination
call getchr; character to apop h
; restore counterpop b; restore next to fill
cpi Cr; end of line?
jz erloop; not end; Store charactermov m,ainx h; next to filldcr c
; counter goes down
jnz rloop; end of buffer?
erloop:; end of read loop, Store 00
mvi m,0; write the record to selected record number
mvi c,Writer
lxi d,fcb
call bdosora a; error code zero?
jnz error; message if not
jmp ready; for another record
; ***
;* *
;* end of Write command, pr0cess Write random zero fill *
;* *
; ***
notw: ; not the quit command; random Write zero fill?
cpi 'F'jnz notf; this is a random Write; fill buffer until cr
lxi d,datmsg
call print; data Prompt
mvi c,127; UP to 127 characterslxi h,buff; destination
rloop1:; read next character to buff
push b; save counter
push h; next destination
call getchr; character to apop h
; restore counterpop b; restore next to fill
cpi cr; end of line?
jz erloop1; not end , store charactermov m,ainx h; next to filldcr c
; counter goes down
jnz rloopl; end of buffer?
erloop1 :; end of read loop, Store 00
mvi m,0; Write the record to selected record number
mvi c,wrtrzf
lxi d,fcb
call bdosora a; error code zero?
jnz error; message if not
jmp ready; for another record
;***
;* *
;* end of Write commands; pr0cess read *
;* *
;***

Digital Research : CP/M 3 Programmer’s Manual
notf :; not a Write command, read record?
cpi 'R'jnz error; skip if not; read random record
mvi c;readr
lxi d,fcb
call bdosora a; return code 00?
jnz error; read was Successful , Write to c0nsole
call crlf; new line
mvi c,128; max 128 characterslxi h,buff; next to getwloop :
mov a,m; next characterinx h; next to getani 7fh; mask Parity
jz ready; for another command if 00
push b; save counter
push h; save next to get
cpi ' '; graphic?
cnc putchr; skip 0utput if not
pop h
pop b
dcr c
; count=count-l
jnz wloop
jmp ready;***;* *;* end of read command , all errors end-up here *
;* *
;***
error :
lxi d,errmsg
call Print
jmp ready;***;* *;* utility subroutines for console I/O *
;i* *
;***
getchr:; read next console character to amvi c,coninp
call bdos
retputchr:; write character a to console
mvi c,conout
mov e ,a; character to Send
call bdos; send character
ret
;
crlf:
; send carriage return line feed
mvi a,cr; carriage returncall putchr
mvi a,lf; line feedcall putchr
ret;parse :
; read and parse filespec
lxi d,c0nbuf
mvi c,rstring
call bdos
lxi d,pfncb
mvi c,parsef
call bdos
retPage 105

Digital Research : CP/M 3 Programmer’s Manual
print:; print the buffer addressed by de Until $push dcall crlf
pop d; new line
mvi c,pstring
call bdos; print the String
ret
readcom:; read the next command line to the conbuf
lxi d,Prompt
call print; command?
mvi c,rstring
lxi d,conbuf
call bdos; read command line
; command line iS present, scan it
mvi c,0; Start With 00
lxi h,0; 0000lxi d,c0nlin; command line
readc: idax d; next command characterinx d; to next command Positionora a; cannot be end of commandrz; not zero, numeric?
sui '0'
cpi 10; carry if numericjnc endrd; add-in next digit
push psw
mov a,c; value in ahl
dad h
adc a
; *2
push a; save value * 2
push h
dad h
; *4
adc a
dad h
; *8
adc a
pop b
; *2 + *8 = *10
dad b
pop b
adc b
pop b
; +digit
mov c,bmvi b,0dad b
aci 0
mov c,ajnc readc
jmp readcom
endrd :
; end of read , restore value in aadi '0'; command
cpi 'a'; translate case?
rc; lower case , mask lower case bits
ani 10101lllb
ret; return with value in chl
;***
;* *
;* string data area for console messages *
;* *
;***
badver:db ' Sorry, you need CP/M version 3$'
nospace :db 'n0 directory space$'
datmsg :db 'type data: $'errmsg :db ' error, try again,$'
Prompt:db 'next command? $'entmsg :db 'enter filename: $'
;***
;* *

Page 106

Digital Research : CP/M 3 Programmer’s Manual

Page 107;* fixed and variable data area *
;* *
;***
conbuf: db conlen; length of console bufferconsiz: ds 1
; resulting size after readconlin: ds 32; length 32 bufferconlen equ $-consiz
pfncb :
dW conlin
dw fcbds 32; 16 level Stack
stack :
end

You could make the following major improvements to this program to enhance its operation. With some work,
this program could evolve into a simple data base management system. You could, for example, assume astandard record size of 128 bytes, consisting of arbitrary fields within the record. You could develop a program
called GETKEY that first reads a sequential file and extracts a specific field defined by the operator. For
example, the command
GETKEY NAMES*DAT LASTNAME 10 20
would cause GETKEY to read the data base file NAMES.DAT and extract the "LASTNAME" field from eachrecord, starting at position 10 and ending at character 20. GETKEY builds a table in memory consisting of eachparticular LASTNAME field, along with its 16-bit record number location within the file. The GETKEY
program then sorts this list and writes a new file, called LASTNAME.KEY. This list, sometimes called aninverted index, is an alphabetical list of LASTNAME fields with their corresponding record numbers.
You could rename the program shown above to QUERY, and modify it so that it reads a sorted key file intomemory. The command line might appear as
QUERY NAMES.DAT LASTNAME.KEY
Instead of reading a number, the QUERY program reads an alphanumeric string which is a particular key tofind in the NAMES.DAT data base. Because the LASTNAME.KEY list is sorted, you can find a particular
entry quickly by performing a binary search, similar to looking up a name in the telephone directory. Start at
both ends of the list and examine the entry halfway in between and, if not matched, split either the upper half or
the lower half for the next search. You will quickly reach the item you are looking for, in log2(n) steps, where
you will find the corresponding record number. Fetch and display this record at the console as the programillustrates.
At this point, you are just getting started. With a little more work, you can allow a fixed grouping size, which
differs from the 128-byte record shown above. You can accomplish this by keeping track of the record number
as well as the byte offset within the record. Knowing the group size, you can randomly access the record
containing the proper group, offset to the beginning of the group within the record, and read sequentially until
the group size has been exhausted.
Finally, you can improve QUERY considerably by allowing Boolean expressions that compute the set ofrecords that satisfy several relationships, such as a LASTNAME between HARDY and LAUREL and an AGE
less than 45. Display all the records that fit this description. Finally, if your lists are getting too big to fit intomemory, randomly access your key files from the disk as well.

4.4 Construction of an RSX ProgramDigital Research : CP/M 3 Programmer’s Manual

Page 108

This section describes the standard prefix of a Resident System Extension (RSX) and illustrates theconstruction of an RSX with an example. (See Section 1.6.4 for a discussion of how RSXs operate under CP/M
3.) RSX programs are usually written in assembler, but you can use other languages if the interface between thelanguage and the calling conventions of the BDOS are set up properly.

4.4.1 The RSX Prefix
The first 27 bytes of an RSX program contain a standard data structure called the RSX prefix. The RSX prefix
has the following format:
serial: d b 0,0,0,0,0,0
start:.
jmp ftest
next : db 0c3h
dw 0
Prev: dw 0
remove: db 0ffh
nonbank: db 0
name: db '123456713'
loader : db 0
db 0,0; start of Program; jump instruction to; next module in line
; Previous module; remove flag
; nonbank flag
; any B-character name; loader flag
; reserved area

The only fields of the RSX prefix that you must initialize are the remove: flag, the nonbank: flag, and the name:of the RSX.
For compatibility with previous releases of CP/M, the serial: field of the prefix is set to the serial number of theoperating system by the LOADER module when the RSX is loaded into memory. Thus, the address in location
6 locates the byte following the serial number of the operating system with or withou; RSXs in memory.
The start: field contains a jump instruction to the beginning of the RSX code where the RSX tests to see if thisBDOS function call is to be intercepted or passed on to the next module in line.
The next: field contains a jump instruction to the next module in the chain or the LOADER module if the RSX
is the oldest one in memory. The RSX program must make its own BDOS function calls by calling the next:
entry point.
The prev: field contains the address of the preceding RSX in memory or location 5 if the RSX is the first RSX
in the chain.
The remove: field controls whether the RSX is removed from memory by the next call to the LOADER module
via BDOS function 59. If the remove: flag is 0fFH, the LOADER removes the RSX from memory. Note that
the CCP always calls the LOADER module during a warm start operation. An RSX that remains in memory
past warm start because its remove: flag is zero, must set the flag at its termination to ensure its removal frommemory at the following warm start.
The nonbank: field controls when the RSX is loaded. If the field is 0FFH, the LOADER only loads the module
into memory on non-banked CP/M 3 systems. Otherwise, the RSX is loaded into memory under both banked
and non-banked versions of CP/M 3.
The loader: flag identifies the LOADER RSX. When the LOADER module loads an RSX into memory, it sets
this prefix flag of the loaded RSX to zero. However, the loader: flag in the LOADER's prefix contains 0FFH.
Thus, this flag identifies the last RSX in the chain, which is always the LOADER.

4.4.2 Example of RSX Use

Digital Research : CP/M 3 Programmer’s Manual

Page 109

These two sample programs illustrate the use of an RSX program. The first program, CALLVERS, prints a
message to the console and then makes a BDOS Function 12 call to obtain the CP/M 3 version number.
CALLVERS repeats this sequence five times before terminating. The second program, ECHOVERS, is an RSX
that intercepts the BDOS Function 12 call made by CALLVERS, prints a second message, and returns theversion 0031H to CALLVERS. Although this example is simple, it illustrates BDOS function interception,
stack swapping, and BDOS function calls within an RSX.
; CALLVERS program
0005 = bdos equ 5; entrY point for BDOS
000B = prtstr equ B; print string funCtion
000C = vers equ 12; get version function
000D = cr equ 0dh; carriage return000A = lf equ 0ah; line feedorg l00h
mvi d,5; Perform 5 times
DS loop: push d; save countermvi c,Prtstr
lxi d,call$msg; Print call message
call bdos
mvi c,vers
call bdos; try to get version *; CALLVERS will intercept
mov a,lsta curvers
pop d
dcr d
; decrement counterJnz loop
mvi c,0JmP bdos
call $msg:
db cr,lf,'**** CALLVERS **** $'curvers db 0
end
; ECHOVERS RSX
000B = pstring equ 9000D = cr equ 0dh
000A = lf equ 0ah
0000 db 0,0,0,0,0,0
Jmp ftest
next: db 0c3H
dw 0
prev: dw 0
remov: db 0ffh
nonbnk: db 0
db 'ECHOVERS'
db 0,0,0
ftest:
mov a,ccpi 12
Jz beginJmp next
begin:
lxi h,0dad spshld ret$stacklxi sp,loc$stack
mvi c,pstring
lxi d,test$msg
call next
lhld ret$stacksphl
lxi h,0031h; string Print function; RSX PREFIX STRUCTURE; room for serial number; begin of Program; Jump; next module in line
; previous module; remove flag set; is this function 12?
; Yes - intercept; some other function; save stack; Print message; call BDDS
; restore user stack; return version number

Digital Research : CP/M 3 Programmer’s Manual

Page 110

ret
test$msg:
db cr,lf,'**** ECHDVERS *** *$'ret$stack:
dw 0
ds 32
; 16 level stack
loc$stack :end

You can prepare the above programs for execution as follows:
1. Assemble the CALLVERS program using MAC as follows:
MAC CALLVERS

2. Generate a COM file for CALLVERS with HEXCOM:HEXCOM CALLVERS

3. Assemble the RSX program ECHOVERS using RMAC:
RMAC ECHOVERS

4. Generate a PRL file using the LINK command:
LINK ECHOVERS [OP]5. Rename the PRL file to an RSX file:
RENAME ECHOVERS.RSX=ECHOVERS.PRL

6. Generate a COM file with an attached RSX using the GENCOM command:
GENCOM CALLVERS ECHOVERS

7. Run the CALLVERS.COM module:
CALLVERS

The message * CALLVERS followed by the message * ECHOVERS **** appears on the screen five times if
the RSX program works.

Digital Research : CP/M 3 Programmer’s Manual

Page 111

Appendix A : System Control Block
The System Control Block (SCB) is a CP/M 3 data structure located in the BDOS. CP/M 3 uses this region
primarily for communication between the BDOS and the BIOS. However, it is also available forcommunication between application programs, RSXS, and the BDOS. Note that programs that access the
System Control Block are not version independent. They can run only on CP/M 3.
The following list describes the fields of the SCB that are available for access by application programs and
RSXS. The location of each field is described as the offset from the start address of the SCB (see BDOS
Function 49). The RW/RO column indicates if the SCB field is Read-Write or Read-Only.
Table A-1. SCB Fields and Definitions
OffsetRW/
RO

00 - 04

RO

Reserved for system use.

05

RO

BDOS Version Number.

06 - 09

RW

Reserved for user use. Use these four bytes for your own flags or data.

0A - 0F

RO

Reserved for system use.

10 - 11RW

Program Error Return Code. This 2-byte field can be used by a program to pass an error codeor value to a chained program. CP/M 3's conditional command facility also uses this field todetermine if a program executes successfully. The BDOS Function 108 (Get/Set Program
Return Code) is used to get/set this value.

12 - 19

RO

Reserved for system use.

1A

RW

Console Width. This byte contains the number of columns, characters per line, on yourconsole relative to zero. Most systems default this value to 79. You can set this default value
by using the GENCPM or the DEVICE utility. The console width value is used by thebanked version of CP/M 3 in BDOS function 10, CP/M 3's console editing input function.
Note that typing a character into the last position of the screen, as specified by the Console
Width field, must not cause the terminal to advance to the next line.

1B

RO

Console Column Position. This byte contains the current console column position.

1C

RW

Console Page Length. This byte contains the page length, lines per page, of your console.
Most systems default this value to 24 lines per page. This default value may be changed byusing the GENCPM or the DEVICE utility (see the CPIM Plus (CPIM Version 3) Operating
System User's Guide).

1D - 21

RO

Reserved for system use.

Definition

Redirection flags for each of the five logical character devices. If your system's BIOS
supports assignment of logical devices to physical devices, you can direct each of the fivelogical character devices to any combination of up to 12 physical devices. The 16-bit word
for each device represents the following:
22 - 2B

RW
Each bit represents a physical device where bit 15 corresponds to device zero and bit 4
corresponds to device 11. Bits zero through 3 are reserved for system use.
You can redirect the input and output logical devices with the DEVICE command (see CP/M

Digital Research : CP/M 3 Programmer’s Manual

OffsetRW/
RO

Page 112

Definition
Plus (CP/M Version 3) Operating System User's Guide).

22 - 23RW

CONIN Redirection Flag.

24 - 25RW

CONOUT Redirection Flag.

26 - 27RW

AUXIN Redirection Flag.

28 - 29RW

AUXOUT Redirection Flag.

2A - 2B

RW

LSTOUT Redirection Flag.

2C

RW

Page Mode. If this byte is set to zero, some CP/M 3 utilities and CCP built-in commands
display one page of data at a time; you display the next page by pressing any key. If this byte
is not set to zero, the system displays data on the screen without stopping. To stop and startthe display, you can press CTRL-S and CTRL-Q, respectively.

2D

RO

Reserved for system use.

2E

RW

Determines if CTRL-H is interpreted as a rub/del character. If this byte is set to 0, then
CTRL-H is a backspace character (moves back and deletes). If this byte is set to 0FFH, then
CTRL-H is a rub/del character, echoes the deleted character.

2F

RW

Determines if rub/del is interpreted as CTRL-H character. If this byte is set to 0, then rub/delechoes the deleted character. If this byte is set to 0FF, then rub/del is interpreted as a CTRLH character (moves back and deletes).

30 - 32

RO

Reserved for system use.

33 - 34

RW

Console Mode. This is a 16-bit system parameter that determines the action of certain BDOS
Console I/O functions. (See Section 2.2.1 and BDOS Function 109, Get/Set Console Mode,for a thorough explanation of Console Mode.)

35 - 36

RO

Reserved for system use.

37

RW

Output delimiter character. The default output delimiter character is $, but you can change
this value by using the BDOS Function 110, Get/Set Output Delimiter.

38

RW

List Output Flag. If this byte is set to 0, console output is not echoed to the list device. If thisbyte is set to 1 console output is echoed to the list device.

39 - 3B

RO

Reserved for system use.

3C - 3DRO

Current DMA Address. This address can be set by BDOS Function 26 (Set DMA Address).
The CCP initializes this value to 0080H. BDOS Function 13, Reset Disk System, also sets
the DMA address to 0080H.

3E

RO

Current Disk. This byte contains the currently selected default disk number. This value
ranges from 0-15 corresponding to drives A-P, respectively. BDOS Function 25, Return
Current Disk, can be used to determine the current disk value.

3F - 43

RO

Reserved for system use.

RO

Current User Number. This byte contains the current user number. This value ranges from 015. BDOS Function 32, Set/Get User Code, can change or interrogate the currently active
user number.

44

Digital Research : CP/M 3 Programmer’s Manual

Page 113

OffsetRW/
RO

45 - 49

RO

Reserved for system use.

4A

RW

BDOS Multi-Sector Count. This field is set by BDOS Function 44,, Set Multi-Sector Count.

Definition

BDOS Error Mode. This field is set by BDOS Function 45, Set BDOS Error Mode.
If this byte is set to 0FFH, the system returns to the current program without displaying any
error messages.
4B

RW
If it is set to 0FEH, the system displays error messages before returning to the current
program. Otherwise, the system terminates the program and displays error messages. See
description of BDOS Function 45, Set BDOS Error Mode, for discussion of the different
error modes.

RW

Drive Search Chain. The first byte contains the drive number of the first drive in the chain,
the second byte contains the drive number of the second drive in the chain, and so on, for up
to four bytes. If less than four drives are to be searched, the next byte is set to 0FFH to signal
the end of the search chain. The drive values range from 0-16, where 0 corresponds to thedefault drive, while 1-16 corresponds to drives A-P, respectively. The drive search chain canbe displayed or set by using the SETDEF utility (see CPIM Plus (Version 3) Operating
System User's Guide).

50

RW

Temporary File Drive. This byte contains the drive number of the temporary file drive. The
drive number ranges from 0-16, where 0 corresponds to the default drive, while 1-16
corresponds to drives A-P, respectively.

51

RO

Error drive. This byte contains the drive number of the selected drive when the last physicalor extended error occurred.

52 - 56

RO

Reserved for system use.

4C - 4F

BDOS Flags. Bit 7 applies to banked systems only. If bit 7 is set, then the system displays
expanded error messages. The second error line displays the function number and FCB
information. (See Section 2.3.13).
57

RO

58 - 59

RW

Date in days in binary since 1 Jan 78.

5A

RW

Hour in BCD (2-digit Binary Coded Decimal).

5B

RW

Minutes in BCD.

5C

RW

Seconds in BCD.

5D - 5E

RO

Common Memory Base Address. This value is zero for non-banked systems and nonzero forbanked systems.

5F - 63

RO

Reserved for system use.

Bit 6 applies only to non-banked systems. If bit 6 is set, it indicates that GENCPM has
specified single allocation vectors for the system. Otherwise, double allocation vectors havebeen defined for the system. Function 98, Free Blocks, returns temporarily allocated blocks
to free space only if bit 6 is reset.

Digital Research : CP/M 3 Programmer’s Manual

Page 114

Digital Research : CP/M 3 Programmer’s Manual

Page 115

Appendix B : PRL File Generation
B. 1 PRL Format
A Page Relocatable Program has an origin offset of 100H bytes that is stored on disk as a file of type PRL. The
format is shown in Table B-1.
Table B-1. PRL File Format
Address

Contents

0001-0002H

Program size

0004-0005H

Minimum buffer requirements (additional memory)

0006-00FFH

Currently unused, reserved for future allocation
The bit map is a string of bits identifying those bytes in the source code that require
relocation. There is one byte in the bit map for every 8 bytes of source code.

0100 + Program
size = Start of bit The most significant bit, bit 7, of the first byte of the bit map indicates whether or not themapfirst byte of the source code requires relocation. If the bit is on, it indicates that relocationis required. The next bit, bit 6, of the first byte corresponds to the second byte of the source
code, and so forth.

B.2 Generating a PRL
The preferred technique for generating a PRL file is to use the CP/M LINK-80", which can generate a PRL filefrom a REL relocatable object file. This technique is described in the Programmer's Utilities Guide for The
CPIM Family of Operating Systems. A sample link command is shown below.
A>link dump[op]Digital Research : CP/M 3 Programmer’s Manual

Page 116

Appendix C : SPR Generation
System Page Relocatable, SPR, files are similar in format to PRL files except that SPR files have an origin
offset of 0000H (see Appendix B). SPR Files are provided as part of the standard CP/M 3 System: the resident
and banked portions of the banked BDOS, named RESBDOS3.SPR and BNKBDOS3.SPR, and the non-banked
BDOS,, named BDOS3.SPR. The customized BIOS must also be generated in SPR format before GENCPM
can create a CP/M 3 system. The BIOS SPR file is named BNKBIOS3.SPR for banked systems andBIOS3.SPR for non-banked systems. A detailed discussion of the generation of BIOS3.SPR or BNKBIOS3.SPR is provided in the CPIM Plus (CP/M Version 3) Operating System System Guide.
The method of generating an SPR is analogous to that of generating a Page Relocatable Program (described inAppendix B) with the following exceptions:

If LINK-80 is used, the output file of type SPR is specified with the [os] or [b] option. The [b] option isused when linking BNKBIOS3.SPR.
The code in the SPR is ORGed at 0000H rather than 0100H.

Digital Research : CP/M 3 Programmer’s Manual

Page 117

Appendix D : ASCII and Hexadecimal Conversions
This appendix contains tables of the ASCII symbols, including their binary, decimal, and hexadecimalConversions.
Table D-1. ASCII Symbols
SymbolMeaning

SymbolMeaning

ACK

acknowledge

FS

file separator

BEL

bell

GS

group separatorBS

backspaceHThorizontal tabulation

CAN

cancelLF

line-feedCR

carriage return

NAK

negative acknowledge

DCdevice control

NUL

null

DEL

deleteRS

record separator

DLE

data link escapeSI

shift inEM

end of medium

SO

shift out

ENQ

enquiry

SOH

start of heading

EOT

end of transmission

SP

space

ESC

escapeSTX

start of text

ETB

end of transmission

SUB

substituteETX

end of text

SYN

synchronous idleFFform-feedUSunit separator

VTvertical tabulation

Table D-2 : ASCII Conversion Table
Binary Decimal Hexadecimal
ASCII
0000000
00
NUL
0000001
1
1
SOH (CTRL-A)
00000102
2
STX (CTRL-B)
00000113
3
ETX (CTRL-C)
0000100
4
4
EOT (CTRL-D)
00001015
5
ENQ (CTRL-E)
00001106
6
ACK (CTRL-F)
00001117
7
BEL (CTRL-G)
0001000
8
8
BS (CTRL-H)
000100199
HT (CTRL-1)
000101010A
LF (CTRL-J)

Digital Research : CP/M 3 Programmer’s Manual
Binary Decimal Hexadecimal
ASCII
000101111B
VT (CTRL-K)
0001100
12C
FF (CTRL-L)
0001101
13
D
CR (CTRL-M)
000111014E
SO (CTRL-N)
000111115F
SI (CTRL-0)
0010000
16
10
DLE (CTRL-P)
001000117
11
DC1 (CTRL-Q)
001001018
12
DC2 (CTRL-R)
001001119
13
DC3 (CTRL-S)
0010100
20
14
DC4 (CTRL-T)
001010121
15
NAK (CTRL-U)
001011022
16
SYN (CTRL-V)
001011123
17
ETB (CTRL-W)
0011000
24
18
CAN (CTRL-X)
0011001
25
19
EM (CTRL-Y)
001101026
1A
SUB (CTRL-Z)
001101127
1B
ESC (CTRL-[)
0011100
28
1C
FS (CTRL-\)
001110129
1D
GS (CTRL-])
001111030
1E
RS (CTRL--)
001111131
1F
US (CTRL-_)
0100000
32
20(SPACE)
010000133
21!
010001034
22"010001135
23#0100100
36
24$
010010137
25%
010011038
26&010011139
27'010100040
28(010100141
29)
0101010422A*010101143
2B+
0101100
44
2C,
010110145
2D
0101110462E.
010111147
2F/
011000048
30
0011000149
31
1011001050
322011001151
33
30110100
52
34
4011010153
35
501101105436
6011011155
37
7Page 118

Digital Research : CP/M 3 Programmer’s Manual
Binary Decimal Hexadecimal
0111000
56
38
011100157
39
011101058
3A
011101159
3B
0111100
60
3C
011110161
3D
011111062
3E011111163
3F
1000000
64
40
100000165
41
100001066
42
100001167431000100
68
44
100010169
45
100011070
46100011171
471001000
72
48
1001001
73
49
100101074
4A
100101182
4B
1001100
83
4C
1001101
84
4D
100111085
4E100111186
4F
1010000
87
50
1010001
88
51
101001089
52101001190
53
1010100
91
54
1010101
92
55
101011093
56101011194
57
1011000
95
58
1011001
96
59
101101097
5A
101101198
5B
1011100
99
5C
1011101 100
5D1011110 101
5E1011111 102
5F
1100000 103
601100001 104
611100010 105
621100011 106
631100100 107
64

ASCII
8
9
:
;
<
=
>
?
@
A
B
c
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
[
\
]
^
<
'
a
b
c
d

Page 119

Digital Research : CP/M 3 Programmer’s Manual
Binary Decimal Hexadecimal
1100101 108
65110011066
1100111671101000
68
1101001
69
1101010
6A
11010116B
1101100
6C
1101101 109
6D1101110 110
6E11011111ll
6F
1110000 112
701110001 113
711110010 114
721110011 115
731110100 116
741110101 117
75
1110110 118
761110111 119
771111000 120
781111001 121
791111010 122
7A1111011 123
7B
1111100 124
7C1111101 125
7D
1111110 126
7E1111111 127
7F

ASCII
e
f
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
w
x
y
z
{
|
}
DEL

Page 120

Digital Research : CP/M 3 Programmer’s Manual

Page 121

Appendix E : BDOS Function Summary
Table E-1. BDOS Function Summary
Function

Function Name

Input Parameters

Returned Values

0

System Reset

none

none

1

Console Input

none

A = Char2

Console Output

E = charA = 00H

3

Auxiliary Input

none

A = char

4

Auxiliary Output

E = charA = 00H

5

List Output

E = charA = 00H

6

Direct Console I/O

E = 0FFH
0FEH
0FDH

A = char
Statusnone

7

Auxiliary Inputnone

A = 00/0FFH Status

8

Auxiliary Output

none

A = 00/0FFH Status

9

Print String

DE = .StringA = 00H

10

Read Console Buffer

DE = .Buffer0

Characters in buffer11

Get Console Statusnone

A = 00/01

12

Return Version Numbernone

HL = Version (0031H)

13

Reset Disk Systemnone

A = 00H

14

Select Disk

E = Disk Number

A = Err Flag

15

Open File

DE = FCBA = Dir Code

16

Close File

DE = FCBA = Dir Code17

Search for FirstDE = FCBA = Dir Code18

Search for Nextnone

A = Dir Code19

Delete File

DE = FCBA = Dir Code20

Read Sequential

DE = FCBA = Err Code21

Write Sequential

DE = FCBA = Err Code22

Make File

DE = FCBA = Dir Code23

Rename File

DE = FCBA = Dir Code

24

Return Login Vectornone

HL = Login Vector

25

Return Current Disknone

A = Cur Disk#

26

Set DMA Address

DE = . DMA

A = 00H

Digital Research : CP/M 3 Programmer’s Manual
Function

Function Name

Input Parameters

Page 122

Returned Values

27

Get Addr(Alloc)none

HL = Alloc

28

Write Protect Disknone

A = 00H

29

Get R/O Vectornone

HL = R/O Vector

30

Set File Attributes

DE = .FCB

A = Dir Code31

Get Addr(DPB)none

HL = DPB

32

Set/Get User CodeE = 0FFH
user number

A = Curr User
00H

33

Read Random

DE = .FCB

A = Err Code34

Write Random

DE = .FCB

A = Err Code35

Compute File Size

DE = .FCB

r0, rl, r2
A = Err Flag

36

Set Random Record

DE = .FCB

r0, rl, r2

37

Reset Drive

DE = Drive Vector

A = 00H

38

Access Drivenone

A = 00H

39

Free Drivenone

A = 00H

40

Write Random with Zero Fill

DE = .FCB

A = Err Code41

Test and Write Record

DE = FCB

A = 0FFH

42

Lock Record

DE = ..FCB

A = 00H

43

Unlock Record

DE = .FCB

A = 00H

44

Set Multi-sector CountE = # Sectors

A = Return Code45

Set BDOS Error Mode

E = BDOS Err Mode A = 00H

46

Get Disk Free SpaceE = Drive number

Number of Free Sectors
A = Err Flag

47

Chain to Program

E = Chain Flag

A = 00H

48

Flush Buffers

E = Purge Flag

A = Err Flag

49

Get/Set System Control Block

DE = .SCB PB

A = Returned Byte
HL = Returned Word50

Direct BIOS Calls

DE = .BIOS PB

BIOS Return

59

Load Overlay

DE = .FCB

A = Err Code60

Call Resident System Extension

DE = .RSX PB

A = Err Code98

Free Blocks

none

A = Err Flag

99

Truncate File

DE = .FCB

A = Dir Code

Digital Research : CP/M 3 Programmer’s Manual
Function

Function Name

Input Parameters

Page 123

Returned Values

100

Set Directory Label

DE = .FCB

A = Dir Code

101

Return Directory Label Data

E = Drive

A = Dir label data byte

102

Read File Date Stamps and Password Mode DE = .FCB

A = Dir Code103

Write File XFCBDE = .FCB

A = Dir Code104

Set Date and Time

DE = .DAT

A = 00H

105

Get Date and Time

DE = .DAT

Date and Time A = seconds

106

Set Default Password

DE = Password

A = 00H

107

Return Serial Number

DE = .Serial field

Serial Number

108

Get/Set Program Return CodeDE = 0FFFFH/CodeHL Program Ret Code/None

109

Get/Set Console Mode

DE = 0FFFFH/Mode HL = Console Mode/none

110

Get/Set Output Delimiter

DE = 0FFFFH
E = Delimiter

A = Output Delimiter/none

111

Print Block

DE = .CCB

A = 00H

112

List Block

DE = .CCB

A = 00H

152

Parse Filename

DE = .PFCB

See definition

Note: . indicates the address ofRevised, reformatted, and restored from original Ami Pro and PS sources by PCPete (PCPete@audiography.com.au) 05MAR2011(Rev 1.12)