CP/M Plus (CP/M® Version 3) Operating System Programmer's Guide

 

Section 1

Introduction to CP/M 3

This section introduces you to the general features of CP/M 3 with an emphasis on how CP/M 3 organizes your computer'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. Subsequent paragraphs describe the components of the operating system, how they communicate with each other and the application program, and in greater detail where each component and program is located in memory. After a brief 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 nonbanked systems. CP/M 3 uses the additional memory available in banked systems to provide functions that are not present in the nonbanked version. For example, the banked version of CP/M 3 supports file passwords; the nonbanked version does not. However, because a nonbanked system treats passwords the same way as a banked system does when password protection is not enabled, an application program can run under either system without modification.

1.1

Banked and Nonbanked Memory Organization

The memory organization for a nonbanked CP/M 3 system is very simple, as shown in Figure 1-1.

[figure 1-1]

Figure 1-1. Nonbanked System Memory Organization

To expand memory capacity beyond the 64K address space of an 8-bit microprocessor, CP/M 3 supports bank-switched memory in a special version called the banked system. In the banked version, the operating system is divided 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. Figure 1-2 shows memory organization under the banked system.

[figure 1-2]

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 in context; that is, it can always be referenced, no matter what bank is switched in. Figure 1-3 shows memory organization when Bank 1 is in context.

[figure 1-3]

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, more memory space is available for transient programs in banked CP/M 3 systems than in nonbanked systems.

The operating system uses the clear areas in Figures 1-2 and 1-3 for disk record buffers and directory hash tables. The clear area in the common region above the operating system represents space that can be allocated for data buffers by GENCPM. Again, the minimum size of this area is determined by the specific hardware requirements of the host microcomputer system.

In the nonbanked 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 the memory 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 and directory 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.

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 system bank and is in context when CP/M 3 is started. Bank 1 is the transient program bank, and must be contiguous from 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]

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 can communicate 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

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

The Basic Input/Output System, BIOS, is a hardware-dependent module that defines the low-level interface to a particular 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 are active.

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 a system 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 and the BDOS, and transient programs and RSXs.

The division of responsibility between the different modules and the way they communicate with one another provide three important benefits. First, because the operating system is divided into two modules--one that is configured 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 of the operating system. This interface consists of a series of entry points in the BIOS that the BDOS calls to perform hardware-dependent primitive functions such as peripheral device I/O. 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, even when 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

Transient programs and the CCP access CP/M 3 facilities by making BDOS function calls. BDOS functions can create, 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 and calls 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 the operating 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 call many 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. This location contains a jump instruction to BIOS base+3, which contains a jump instruction to the BIOS warm start routine. The BIOS warm start routine loads the CCP into memory at location 100H and then passes control to it. 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 when necessary, 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. Nonintercepted 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, can attach 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.

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 avialable for the execution of transient programs. Figure 1-6 reviews the location of regions in logical memory.

[figure 1-6]

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 system modules 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 directory hashing or data buffering by GENCPM. The maximum top of memory address for both banked and nonbanked 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 is determined by the requirements of the host computer system.

The size of the BDOS region differs for the banked and nonbanked versions of CP/M 3. In the banked version, the resident BDOS size is 6 pages, 1.5K. In the nonbanked 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 the configuration 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 is attached 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.

The 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, by using 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 P, 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, are commonly divided up into multiple logical drives. Figure 1-7 illustrates the standard organization of a CP/M 3 disk.

[figure 1-7]

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 the files that exist on the drive and identifies the data space that belongs to each file. The data area contains the file data 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 is subdivided 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 by calling 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, these fields 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 an eight-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 wildcard 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 directory or data space is available for a requested operation, the BDOS returns an error to the calling program. In general, the allocation and deallocation 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 system facilities 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 not describe 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 area of 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 in memory. Once CPMLDR has loaded the BDOS and BIOS into memory, it sends a sign-on message to the console 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 a variant CPMLDR-BIOS that is adapted to match the host microcomputer hardware environment. Cold start initialization of I/O ports and similar functions can also be performed in the CPMLDR-BIOS module during the third stage of cold start.

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 Start function 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 the system tracks for the CCP, it is usually loaded from there. If there is not enough space in the system tracks, the BIOS 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 to warm 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 is accomplished 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 chosen when the system is configured. However, CPMLDR locates the BDOS and BIOS system components in memory 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 the system 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 not running. It also reads the user's command lines, differentiates between built-in commands and transient commands, and executes the commands accordingly.

This section describes the responsibilities and capabilities of the CCP in some detail. The section begins with a description 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 the procedure 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. This signifies 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 the initial 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).

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 in memory 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

<command>
<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:
"=,[]<> "
d:
CP/M 3 drive specification,"A" through "P"
filename
1 to 8 character filename
typ
1 to 3 character filetype
password
1 to 8 character password value

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 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 their command 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. 

B>USER 15
15B>

The following table summarizes the built-in commands.

Table 1-1. CP/M 3 Built-in Commands

Command
Meaning
DIR
displays a list of all filenames from a disk directory except those marked with the SYS attribute.
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 built-in 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 perform the 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 a submit file. If the CCP identifies a command keyword as a transient program, the transient program file is loaded into the TPA from disk and executed. If it recognizes a submit file, the CCP reconstructs the command line into the following form: 

SUBMIT <command> <command tail>
and attempts to load and execute the SUBMIT utility. Thus, the original command field becomes the first command 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 transient commands 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 the optional filetype field is omitted from the command, the CCP usually assumes the command field references a file 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 the command filetype field is omitted. When this automatic submit option is in effect, the CCP attempts to open the command with a filetype of COM. If the COM file cannot be found, the CCP repeats the open operation with a filetype of SUB. As an alternative, the order of open operations can be reversed so that the CCP attempts to open with a filetype of SUB first. In either case, the file that is found on disk first determines the filetype field that is ultimately associated with the command.
    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 of command and submit files. If an open operation is unsuccessful on a drive in the drive chain because the file cannot 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 the current 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, the file 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 a disk 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 mark to 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 access by the loaded transient program:
    0050H
    Drive that the command file was loaded from
    0051H
    Password address of first file in command tail
    0053H
    Password length of first file in command tail
    0054H
    Password address of second file in command tail
    0056H
    Password length of second file in command tail
    005CH
    Parsed FCB for first file in command tail
    006CH
    Parsed FCB for second file in command tail
    0080H
    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 to contain the file. If no RSXs are resident in memory, the available TPA space is determined by the address LOADER_base because the LOADER cannot load over itself. Otherwise, the maximum TPA address is determined 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 of Page Zero to address the lowest RSX in memory. Finally, the LOADER discards the RSX header and relocates the 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 to location 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 into memory. 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 this step 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 name transient implies, transient programs are not system resident. The CCP must load a transient program into memory every time the program is to be executed. For example, the utilities PIP and RMAC that are shipped with 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 32-byte 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 the command 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.

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 execution of 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.DAT
A>REPORT RESULTS.DAT

The 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 file structure, 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 to modify or extend the functionality of the BDOS. RSX modules intercept BDOS functions and either perform them, 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 file specified 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 a command file, it calls the LOADER module to load the program into the TPA. The LOADER loads the transient 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 to point 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 have a 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 a transient program. In this case, the command file consists of the RSX header followed by the RSXs.

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

[figure 1-8]

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 of Page Zero to the BDOS entry point. The RSX flags are the Remove flag and the Nonbanked 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 nonbanked flag identifies RSXs that are loaded only in nonbanked CP/M 3 systems. For example, the CP/M 3 RSX, DIRLBL.RSX, is a nonbanked RSX. It provides BDOS Function 100, Set Directory Label, support for nonbanked systems only. Banked systems support this function 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. Nonintercepted 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 indicates that 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 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 the command 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 file drive 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-file on 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 system component. The SCB contains internal BDOS flags and data, CCP flags and data, and other system information such as console characteristics and the current date and time. The BDOS, BIOS, CCP system components as well 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 parameters that reflect the current state of the operating system. If a program modifies these parameters illegally, the operating system might crash. However, for application writers who are writing system-oriented applications, access to the SCB variables might prove valuable.

For 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, the current 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 3 for more information on the System Control Block. The SCB fields are also discussed in Appendix A.

End of Section 1

Continue in...
Top of this document
Index
Section 2
Section 0
Main

page URL: www.bigfoot.com/~c128page/cpm3-prg/cpm3prg1.htm
contact: c128page@bigfoot.com