CP CPM Betriebsanweisung

CP/M Plus(CP/M (R) Version 3)Operating SystemProgrammers Guide

To expand memory capacity beyond the 64K address space of an 8-bit micropro- cessor, CP/M 3 supports bank-switched memory in a special versio

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

In nonbanked systems, file passwords and XFCBs are not supported. Thus, if the Delete function is called with interface attribute f5' set

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

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 e

BDOS FUNCTION 21: WRITE SEQUENTIAL Entry Parameters: Registers C: 15H

Upon return, the Write Sequential function sets register A to zero if the write operation is successful. Otherwise, register A contains an er

Error Code 255 is returned if a physical error is encountered and the BDOS error mode is Return Error mode, or Return and Display E

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

If the Make function is successful, it activates the referenced FCB for file opera- tions by opening the FCB, and initializes bot

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

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 s

CP/M 3 Programmer's Guide 3 BDOS Calls: Function 23 Upon return, the Rename function returns

BDOS FUNCTION 24: RETURN LOGIN VECTOR Entry Parameters: Register C: 18H

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

BDOS FUNCTION 26: SET DMA ADDRESS Entry Parameters: Registers C: 1AH

BDOS FUNCTION 27: GET ADDR(ALLOC) Entry Parameters: Register C: 1BH

BDOS FUNCTION 28: WRITE PROTECT DISK Entry Parameters: Register C: 1CH The Write Protect

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

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

File attributes tl', t2', and t3' are defined by CP/M 3. (They are described in Section 2.3.4.) Attributes fl'

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

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 numb

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

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

Upon return, the Read Random function sets register A to zero if the read opera- tion was successful. Otherwise, register A contain

BDOS FUNCTION 34: WRITE RANDOM Entry Parameters: Registers C: 22H

If the BDOS Multi-Sector Count is greater than one (see Function 44), the Write Random function reads multiple consecutive record

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

BDOS FUNCTION 35: COMPUTE FILE SIZE Entry Parameters: Registers C

Upon return, Function 35 returns a zero in register A if the file specified by the referenced FCB is found, or an OFFH in register A if the fil

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

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

Figure 1-5. System Components and Regions in Logical Memory The Basic Input/Output System, BIOS, is a hardware-dependent module that defines t

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

BDOS FUNCTION 39: FREE DRIVE Entry Parameters: Register C: 27H This is an MP/M funct

BDOS FUNCTION 40: WRITE RANDOM WITH ZERO FILL

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

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

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

BDOS FUNCTION 44: SET MULTI-SECTOR COUNT Entry Parameters: Registers C: 2CH

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

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

Upon return, register A is set to zero if the function is successful. However, if the BDOS Error Mode is one of the return modes (see Function 4

The Transient Program Area, TPA, is the region of memory where transient pro- grams execute. The CCP also executes in this region.

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

BDOS FUNCTION 48: FLUSH BUFFERS Entry Parameters: Registers C: 30H Return

BDOS FUNCTION 49: GET / SET SYSTEM CONTROLBLOCK

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

Table 3-4. (continued) Offset Description 3C-3D

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

BDOS FUNCTION 59: LOAD OVERLAY Entry Parameters: Registers C: 3

BDOS FUNCTION 60: CALL RESIDENT SYSTEM EXTENSION Entry Parameters:

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

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

1.3.2 Applications and the BDOS Transient programs and the CCP access CP/M 3 facilities by making BDOS func- tion calls. BDOS function

Function 99 also requires that the random record number field of the referenced FCB specify a value less than the current file size.

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

Function 100 also requires that the referenced directory contain SFCBs to activate date and time stamping on the drive. If an atte

BDOS FUNCTION 101: RETURN DIRECTORY LABEL DATA Entry Parame

BDOS FUNCTION 102: READ FILE DATE STAMPS AND PASSWORD MODE Entry Parameters:

Upon return, Function 102 returns a Directory Code in register A with the value zero if the function is successful, or OFFH, 255 decimal, i

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

Upon return, Function 103 returns a Directory Code in register A with the value zero if the XFCB create or update is successful, or OFFH, 255

BDOS FUNCTION 104: SET DATE AND TIME Entry Parameters: Registers C

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

1.3.3 Applications and RSXs A Resident System Extension is a temporary additional operating system module. An RSX can extend or m

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

BDOS FUNCTION 107: RETURN SERIAL NUMBER Entry Parameters: Registers C: 6BH

BDOS FUNCTION 108: GET/SET PROGRAM RETURN CODE Entry Para

Table 3-5. Program Return Codes Code Meaning 0000 - FEFF Successful return F

BDOS FUNCTION 109: GET/SET CONSOLE MODE Entry Parameters: Registers C: 6DH

bits 8,9 -Console status mode for RSXs that perform console input redirec- tion from a file. These bits determine how the RS

BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER Entry Parameters: Registers C: 6EH

BDOS FUNCTION111: PRINT BLOCK Entry Parameters: Registers C: 6FH

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

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

Figure 1-6. System Modules and Regions in Logical Memory First note that all memory regions in CP/M 3 are page-aligned. This

The Parse Filename function parses the first file specification it finds in the input string. The function first eliminates leadin

Table 3-6. FCB Format Location Contents byte 0 The dri

If an error occurs, Function 152 returns an 0FFFFH in register pair HL. On a successful parse, the Parse Filename function checks

Section 4Programming Examples The programs presented in this section illustrate how to use the BDOS functions described in the previou

; 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 d

; source and destination fcbs ready;0117 1l5c00 lxi d,sfcb ; source file0lla cd690l call 0pen ; error if 2550lid 118701 lxi d,nofile; ready message01

; system interface subroutines; (all return directly from bdos)0169 0e0f open: mvi c ,openf016b c30500 Jmp bdos016e 0el0 close: mvi c,closef0170 c305

4.2 A Sample File Dump Utility The following dump program reads an input file specified in the CCP command line, and then disp

; file not there, give error message and return0112 11f301 lxi d,opnmsg0115 cd9c0l call err0118 c35101 jmp finis ;to returnopenok: ;open operatio

;finis:; end of dump0151 cd7201 call crlf0154 2a1502 lhld oldsp0157 f9 sphl; stack pointer contains ccp's stack location0158 c9

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

phex: ;Print hex char in reg a018f f5 push psw0190 0f rrc0191 0f rrc0192 0f rrc0193 0f rrc0194 cd7d0l call pnib ;print nibble0197 fi pop pSW0198

; open the file for input01c1 af xra a ;zero to accum01c2 327c00 sta fcbcr ;clear current rec0rd0lc5 115c00 lxi d,fcb01c8 0e0f mvi c,openf0l

4.3 A Sample Random Access Program This example is an extensive but complete example of random access operation. The following program reads

The program begins with an initialization section where the input file is opened or created, followed by a continuous loop at the la

;************************************;* *;* load SP, Set-up file for random access *;* *;************************************0100 313703 lxi sp,stack;

; ******************************************;* *;* loop back to "ready" after each command *;* *;******************************************r

; not end; Store character0185 77 mov m,a0186 23 inx h +;inext to fill0187 0D dcr c +;icounter goes down0188 C27901 jnz rloop +;iend of buffer?erlo

erloop1 :; end of read loop, Store 000lbE 3600 mvi m,0; Write the record to selected record number0lc0 0E28 mvi c,wrtrzf01C2 115C00 lxi d,fcb01C5 C

;******************************************;* *;* end of read command , all errors end-up here *;* *;******************************************e r ro

print:;print the buffer addressed by de Until $0231 D5 push d0232 CD1502 call crlf0235 Dl pop d ;new line0236 0E09 mvi c,pstring0238 CD0so0 call bdos

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/

; add-in next digit025D F5 push psw025E 79 mov a,c ;value in ahl025F 29 dad h0260 8F adc a +;i*20261 F5 push a +;isave value *

Prompt:02D1 6E65787420 db 'next command? $'entmsg :02E0 656E746572 db 'enter filename: $';******************************;* *;* fix

Instead of reading a number, the QUERY program reads an alphanumeric string which is a particular key to find in the NAMES.DAT data base. Becaus

4.4.1 The RSX Prefix The first 27 bytes of an RSX program contain a standard data structure called the RSX prefix.

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:

; CALLVERS program0005 = bdos equ 5 ; entrY point for BDOS000B = prtstr equ B ; print string funCtion000C = vers equ 12 ; get version function000D = c

ftest: ; is this function 12?001B 79 mov a,c001C FE0C cpi 12001E CA2400 Jz begin ; Yes - intercept0021 C30500 Jmp next ; some other functionbegin:0024

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

Appenix ASystem Control Block The System Control Block (SCB) is a CP/M 3 data structure located in the BDOS. CP/M 3 uses this region pr

Table A-1. (continued) Offset RW/RO Definition 1A RW Console Width. This byte contains the

COPYRIGHT Copyright 01983 Digital Research Inc. All rights reserved. No part of this publication maybe reproduced, transmitted, transcribed, stor

The directory identifies each file with an eight-character filename and a three- character filetype. Together, these fields must be

Table A-1. (continued) Offset RW/RO Definition 22 - 23 RW CONIN Redirection

+Table A-1. (continued) Offset RW/RO Definition 35 - 36 RO Reserved for system use. 37

Table A-1. (continued) Offset RW/RO Defint.tion 4B RW BDOS Error Mode.

Table A-1. (continued) Offset RW/RO Definition 57 RO BDOS Flags. Bit 7 applies to banked sy

Appendix BPRL File Generation B. 1 PRL Format A Page Relocatable Program has an origin offset of 100H bytes that is stored on disk

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 file from a

Appendix CSPR Generation System Page Relocatable, SPR, files are similar in format to PRL files except that SPR files have an origin o

Appendix DASCII and Hexadecimal Conversions This appendix contains tables of the ASCII symbols, including their binary, deci- mal, and

Binary Decimal Hexadecimal ASCII 0000000 000 00 NUL 00

Table D-2. (continued) ersions Binary Decimal Hexadecimal ASCII 0100101 037

1.6.1 Cold Start Operation The cold start procedure is typically executed immediately after the computer is turned on. The cold start bring

Table D-2. (continued) Binary Decimal Hexadecimal ASCII 1001010 074 4A

Table D-2. (continued) Binary Decimal Hexadecimal ASCII 1100111 103 67 g

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

Table E-1. (continued) Function Function Name Input Parameters Returned Values 25 Return Current Disk none

Table E-1. (continued) Function I Function Name Input Parameters Returned Values 98 Free Blocks none

? in filename error, 2-30 Basic Disk operating System $$$ filetype, 1-27 See BDOS

system, 1-3 byte count, 2-28 version requirements, 1-5 bank-switching, 1-4 C

parsing, 1-17 CTRL-F, 3-14 common memory, 1-3, 1-5 CTRL-G, 2-4, 3-14 base address, 3-71

2-23, 2-25, 3-35, Disk Parameter Block 3-81, 3-85 (DPB), 3-46 DATE utili

extended, 2-29, 2-34 parse, 3-96 file exists, 2-30 filespec, 1-17 flag, 2-33

The fourth and final stage in the cold start procedure is performed by the BIOS Cold Start function, Function 0. The entry point to

28: Write Protect Disk, 3-42 112: List Block, 3-95 29: Get Read-Only Vector, 152: P

106: Set Default Password, I 3-87 107: Return Serial Number, information address, 2-1

auxiliary output device, 2-2 multi-user operating system, AUXIN, 2-2 1-19, 1-28 AUXOLJT, 2-2

SCB, 3-69 RANDOM, 4-10 parameter substitutions, 1-27 parse,

restoring values, 2-1 search chain, 1-20 saving values, 2-1 Search For First, 3-24 REL, 2-11

RSX Parameter Block, 3-74 sparse, 2-12 rub/del, 3-13 sparse file, 2-12 SPR, 2-11

System File, 2-11 VALUE parameter, 3-69 System Reset, 3-1 version-independent

Index

1.6.2 CCP Operation The Console Command Processor provides the user access to CP/M 3 facilities when transient programs are not running.

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

The command field must identify either a built-in command, a transient program, or a submit file. For example, USER is the keyword that iden

All command keywords that do not identify built-in commands identify either a transient program file or a submit file. If the CCP id

If the command field is preceded by a drive specification id:), the CCP attempts to open the command or submit file on the spec

4. When the CCP successfully opens the command file, it initializes the follow- ing Page Zero fields for access by the l

When a transient program terminates execution, the BIOS warm start routine reloads the CCP into memory. When the CCP receives control, it te

Foreword CP/M@ 3 is a microcomputer operating system designed for the Intel 8080, Intel 8085, or othercompatible microprocessor. To run CP/M 3, your

A transient program can terminate execution in one of three ways: by jumping to location 0000H, by making a BDOS System Reset call

A Resident System Extension (RSX) is a special type of program that can be attached to the operating system to modify or extend the functiona

Figure 1-8. RSX File Format RSX files begin with a one page PRL header that specifies the total siz

When the CCP gains control after a system warm start, it removes any RSXs in memory that have the Remove flag set to OFFH. All other R

When the SUBMIT utility begins execution, it opens and reads the file specified by <filespec> and creates a temporary submit

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 Resear

Section 2The BDOS System Interface This section describes the operating system services available to a transient pro- gram through t

The following example illustrates how a transient program calls a BDOS function. This program reads characters continuously until it encounte

Read a character from CONIN: Read a character buffer from CONIN: Write a character to CONOUT: Wri

The basic I/O functions also monitor the console to stop and start console output scroll at the user's request. To provide this suppo

Table of Contents 1 Introduction to CP/M 3 1.1 Banked and Nonbanked Memory Organiza

Function 10 also filters input for certain control characters. If the user types a CTRL-C as the first character in the line, Func

bit 3 : This bit disables all CTRL-C intercept action in the BDOS. This mode is useful for programs that must control their own termin

Transient programs depend on the BDOS file system to create, update, and main- tain disk files. This section describes the capab

BDOS directory functions operate on existing file entries in a drive's directory. This category includes functions to search for one or m

Disk System Reset Drive Selection File Creation File Open File Close Directory Sear

The drive specifier field specifies the drive where the file is located. The filename and type fields identify the file. The password field sp

Function 152 also excludes all control characters from the file fields, and translates all lower-case letters to upper-case.

Table 2-2 displays the relationship between data block size and drive capacity. Table 2-2. Logical Drive Capac

Source files under CP/M 3 are treated as a sequence of ASCII characters, where each line of the source file is followed by a car

where dr drive code (O - 16) 0 = > use default drive for file

Table of Contents (continued) 2.3.13 BDOS Error Handling 2-28 2.4 Page Zero Initialization 2-34 3 BDOS Function Calls

d0 ... dn filled-in by CP/M 3, reserved for system use cr current record

The BDOS updates the memory copy of the FCB during file processing to maintain the current position within the file. During file write opera

t2': System attribute - This attribute, if set, identifies the file as a CP/M 3 system file. System files are not usually di

2.3.5 User Number Conventions The CP/M 3 User facility divides each drive directory into sixteen logically inde- pendent directories, d

2.3.6 Directory Labels and XFCBs The BDOS file system includes two special types of FCBS: the XFCB and the Directory Label. T

An XFCB can be created only on a drive that has a directory label, and only if the directory label has activated password protection. For

Only one Directory Label can exist in a drive's directory. The Directory Label name and type fields are not used to search for

Table 2-4. Password Protection Modes Password Access level allowed wben the Password

File passwords are eight bytes in length. They are maintained in the XFCB Direc- tory Label in encrypted form. To make a BDOS functi

Table 2-6. SFCB Subfields Format Offset in Bytes I SFCB Subfield Contents

Table of Contents (continued) Tables 2-1. Valid Filename Delimiters

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

Note: the CCP automatically discards all pending physical data buffers when it receives control following a system warm start. However, the BD

2.3.11 Disk Reset and Removable Media The BDOS functions, Disk Reset (function 13) and Reset Drive (function 37) allow a progr

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 to store an

The BDOS Error Mode, which can exist in three states, determines how the file system handles physical and extended errors. In the def

The Read-Only File error is returned when a program attempts to write to a file that is marked with the Read-Only attribute. It is also return

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

2.3 BDOS File System CP/M 3 Programmer's Guide The following BDOS functions return a Directory Code in register

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

2.3 BDOS File System CP/M 3 Programmer's Guide Table 2-10. BDOS Physical and Extended Er

Table of Contents (continued) Figures 1-1. Nonbanked System Memory Organization 1-2

Table 2-11. Page Zero Areas Location Contents From

Table 2-11. (continued) Location Contents From TO 005 6H

The CCP initializes Page Zero prior to initiating a transient program. The fields at 0050H and above are initialized from the comman

The default DMA address for transient programs is 0080H. The CCP also initial- izes this area to contain the command tall of the command lin

Section 3BDOS Function Calls This section describes each CP/M 3 system function, including the parameters a program must pass when call

BDOS FUNCTION 1: CONSOLE INPUT Entry Parameters: Register C: 01H Ret

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

BDOS FUNCTION 3: AUXILIARY INPUT Entry Parameters: Register C: 03H Returned Value:

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

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

Section 1Introduction to CP/M 3This section introduces you to the general features of CP/M 3 with an emphasis on how CP/M 3organizes your computer&apo

BDOS FUNCTION 6: DIRECT CONSOLE I/0 Entry Parameters: Registers C: 06H

3 BDOS Calls: Function 6 CP/M 3 Programmer's Guide Table 3-1. Function 6 Entry Paramet

BDOS FUNCTION 7: AUXILIARY INPUT STATUS Entry Parameters: Register C: 07H

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

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

BDOS FUNCTION 10: READ CONSOLE BUFFER Entry Parameters: Registers C: 0AH

When a program calls Function 10 with an initialized buffer, Function 10 operates as if the user had typed in the string. When Fun

The banked version of CP/M 3 expands upon the editing provided in the non- banked version. The functionality of the two versions is simila

Table 3-3. (continued) Character Edit Control Function

BDOS FUNCTION 11: GET CONSOLE STATUS Entry Parameters: Register C: OBH Ret

1.1 Banked and Nonbanked Memory OrganizationThe memory organization for a nonbanked CP/M 3 system is very simple, as shown in Figure1-1.

BDOS FUNCTION 12: RETURN VERSION NUMBER Entry Parameters: Register C: 0CH

BDOS FUNCTION 13: RESET DISK SYSTEM Entry Parameters: Register C: ODH The Reset D

BDOS FUNCTION 14: SELECT DISK Entry Parameters: Registers C: 0E

BDOS FUNCTION 15: OPEN FILE Entry Parameters: Registers C: OFH

If the open operation is successful, the user's FCB is activated for read and write operations. The relevant directory inform

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

Upon return, the close function returns a directory code in register A with the value 00H if the close was successful,, or FFH, 255 D

BDOS FUNCTION 17: SEARCH FOR FIRST Entry Parameters: Registers C: 11H

Upon return, the Search function returns a Directory Code in register A with the value 0 to 3 if the search is successful, or OFFH, 2

BDOS FUNCTION 18: SEARCH FOR NEXT Entry Parameters: Register C: 12H Returned Value: