💾 Archived View for mirrors.apple2.org.za › active › ftp.apple.asimov.net › images › cpm › os › A2.C… captured on 2024-08-19 at 04:28:38.
View Raw
More Information
-=-=-=-=-=-=-
Apple2 CPM Reference
CP/M ver 1.4 & 2.x Programmer's Reference Guide
========================================================
BUILT-IN COMMANDS
=================
DIR Display file directory, current drive
DIR d: Display file directory, designated drive
DIR filename.typ Search for file name, current drive
DIR *.typ Display all files of named type, curr drive
DIR filename.* Display all types of designated filename
DIR x????.* Display all filenames 5 characters long and
starting with letter x
TYPE filename.typ Display ASCII file, current drive
TYPE d:filename.typ Display ASCII file, designated drive
ERA filename.typ Erase named file, current drive
ERA *.* Erase all files, curr drv, ver 2.x curr user
ERA *.typ Erase all files, current drive
ERA d:filename.typ Erase named file, designated drive
ERA filename.* Erase all types of named file, current drive
REN nuname.typ=olname.typ Rename file, current drive
REN d:nuname.typ=olname.typ Rename file, designated drive
SAVE n filename.typ Save as named file, current drive
SAVE n d:filename.typ Save as named file, designated drive
n pages (page = 256 bytes) starting at 100H
d: Switch to designated drive, making it current drive
V 1.4: A-D V 2.x: A-P
USER n Change user area (n=0 to 15) (ver 2.x)
TRANSIENT COMMANDS
==================
DDT Initiate Dynamic Debugging Tool
DDT filename.typ Initiate DDT and load named file
ASM filename Assemble named ASM file on current drive
ASM d:filename Assemble named ASM file on designated drive
ASM filename.abc Assemble named ASM file:
a = source file drive
b = HEX file destination drive (Z=skip)
c = PRN file destination drive (X=console,Z=skip)
LOAD filename Make COM file from named HEX file on current drive
LOAD d:filename Make COM file from named HEX file on design. drive
DUMP filename.typ Display file in hex, current drive
DUMP d:filename.typ Display file in hex, designated drive
MOVCPM Relocate and execute (max) KByte CP/M system
MOVCPM n Relocate and execute n KByte CP/M system
MOVCPM n * Create relocated image in RAM of n Kbyte
CP/M system, ready for SYSGEN or SAVE
MOVCPM * * Create relocated image in RAM of (max) Kbyte
CP/M system, ready for SYSGEN or SAVE
SYSGEN Initiate SYStem GENerate program
SUBMIT filename parameters Execute SUB file using optional parameter(s)
XSUB Execute eXtended SUBmit program (V2.x)
ED filename.typ Execute EDitor to create or edit named file
ED d:filename.typ Execute EDitor to create or edit named file
STAT Display STATus (R/W or R/O) \/ current drive
STAT d: and available disk space /\ design. drive
STAT DEV: Display DEVice assignments
STAT VAL: Display VALid device assignments
STAT DSK: Display DISK characteristics (V2.x)
STAT USR: Display current USeR areas (V2.x)
STAT filename.typ $S Display size of file (V2.x)
STAT fiename.typ Display file characteristics, current drive
STAT d:filename.typ Display file characteristics, designated drive
STAT d:=R/O Change designated drive to Read-Only
STAT filename.typ $R/O Change named file to Read-Only (V2.x)
STAT filename.typ $R/W Change named file to Read-Write (V2.x)
STAT filename.COM $SYS Change named file to System file (V2.x)
STAT filename.COM $DIR Change named file to Directory file (V2.x)
STAT gd:=pd: Change general device (CON:,LST:,PUN:,RDR:)
assignment of physical device (IOBYTE)
PIP
===
Commands
--------
PIP Initiate Peripheral Interchange Program
- d:=s:filename.typ Copy named file from source drive to dest drive
- d:nuname.*=s:olname.typ Copy & rename from source drive to dest drive
PIP d:=s:filename.typ Initiate PIP and copy named file
PIP d:=s:*.* from source drive \/ all files
PIP d:=s:filename.* to || all named files
PIP d:=s:*.typ destination drive /\ all files named type
PIP LST:=filename.typ Send named file to list device
PIP PUN:=filename.typ Send named file to punch device
PIP CON:=filename.typ Send named file to console device
PIP filename.typ=RDR: Copy data from reader device to named file
- nuname.typ=aname.typ,bname.typ,cname.typ ASCII copy & concatenate
- nuname.typ=aname.typ,bname.typ ASCII copy & concatenate
- nuname.typ=aname.typ[X],bname.typ[X] binary copy & concatenate
PIP LST:=aname.typ,bname.typ Send files in sequence to list device
PIP LST:=s:aname.typ,s:bname.typ Send files in sequence to list device
PIP allows access to any logical and physical devices defined in the
CP/M system. Logical devices: CON: RDR: PUN: LST:
Physical devices: TTY: CRT: PTR: UR1: UR2: PTP: UP1: UP2: LPT: UL1:
Special PIP devices (locations 109H to 1FFH are not used in the PIP
image and can be replaced by used drivers using DDT)
NUL: Send 40 NUL's (ASCII 00H) to the device
(can be issued at the end of punched output)
EOF: Send a CP/M EOF (ASCII Ctrl-Z=1AH) to dest device
(sent automatically at end of ASCII transfers thru PIP)
INP: Special PIP input source which can be patched into PIP:
PIP gets input from here by calling 103H, with data
returned at 109H)
OUT: Special PIP output destination which can be patched into PIP:
PIP calls 106H with data to be output in C for each char.
PRN: Same as LST: except that tabbs are expanded to every 8th
column, lines are numbered, and page ejects are inserted
every 60 lines with an initial eject (same as PIP options [t8np])
Parameters
----------
example *filename.typ=RDR:[B]
[B] - read data block until ^S (ctrl-S) character
[Dn] - delete characters past column n
[E] - echo all copy operations to console
[F] - remove form feeds
[Gn] - get file from user area n (V2.x)
[H] - check for proper HEX format
[I] - same as H plus ignores ":00"
[L] - change all upper case characters to lower case
[N] - add line numbers without leading zeros
[N2] - same as N plus leading zeros and a TAB after number
[O] - object file transfer; ignore end-of-file (Ctrl-Z)
[P] - insert form feed every 60 lines
[Pn] - insert form feed every n lines
[Qstring^Z] - Quit copying after string is found
[R] - read SYS file (V2.x)
[Sstring^Z] - Start copying when string is found
[Tn] - expand tab space to every n columns
[U] - change all lower case characters to upper case
[V] - verify copied data (destination must be disk file)
[W] - delete R/O files at destination (V2.x)
[X] - copy non-ACII files
[Z] - zero parity bit (hi bit) on all characters in file
Keywords
--------
CON: CONsole device (defined in BIOS)
EOF: send End-of-File (ASCII ^Z) to device
INP: INPut source (pathced in PIP)
LST: LiST device (defined in BIOS)
NUL: send 40 NUL's to device
OUT: OUTput destination (pathced in PIP)
PRN: same as LST:; tabs every 8th char, number lines & page
ejects every 60 lines with initial eject
PUN: PUNch device (defined in BIOS)
RDR: ReaDeR device (defined in BIOS)
COMMAND CONTROL CHARACTERS
==========================
Control char ASCII code Function
C 03h Reboot - CP/M warm boot
E 05h Start new line
H 08h Backspace and delete (V2.x)
I 09h Tab 8 columns
J 0Ah Line feed
M 0Dh Carriage return
P 10h Printer on/Printer off
R 12h Retype current line
S 13h Stop display outout (any char except ^C restarts)
U 15h Delete line
X 18h Same as � (V1.4)
Z 1Ah End of console input (ED & PIP)
delete/rubout 7Fh Delete and display character (tape only)
ASM
===
Conventions
-----------
line# label operation operant ;comment
labels followed by colon 1-16 alphanumeric characters
symbol (eq. EQU) no colon first must be alpha, ? or .
labels are case insensitive (treated as uppercase)
$ is insignificant and can be inserted
anywhere for readability
Assembly Program Format (space separates fields)
[line#] label: opcode oerand(s) ;comment
Constants
A number of digits with a suffix:
B binary
O or Q octal
D decimal (default)
H hexadecimal
Reserved words in operand fields
The names of the 8080 registers are reserved, and produce the
following values if encountered in the operand field:
A 7
B 0
C 1
D 2
E 3
H 4
L 5
M 6
SP 6
PSW 6
Mnemonics for machine instructions are reserved and evaluate to
their internal codes. Instructions which require operands will
get zeroes in their operand fields, e.g. MOV will produce 40H
The symbol $ in the operand field evaulates to the address of
the next instruction to generate, not including the instruction
within the current logical line
String constants are delimieted by an apostrophe ('), and a
double apostrophe ('') will produce one apostrophe
Operators (unsigned)
a+b a added to b
a-b difference between a and b
+b 0+b (unary addition)
-b 0-b (unary subtraction)
a*b a multiplied by b
a/b a divided by b (integer)
a MOD b remainder after a/b
NOT b complement all b-bits
a AND b bit-by-bit AND of a and b
a OR b bit-by-bit OR of a and b
a XOR b bit-by-bit XOR of a and b
a SHL b shift a left b bits, end off, zero fill
a SHR b shift a right b bits, end off, zero fill
Hierarcy of operations
highest: * / MOD SHL SHR
- +
NOT
AND
OR XOR
Pseudo-ops
ORG const Set program or data origin (Default=0)
END start End program, optional address where excution begins
EQU const Define symbol value (may not be changed)
SET const Define symbol value (may be changed later)
IF const Assemble block conditionally until ENDIF
ENDIF Terminate conditionala ssembly block
DS const Define storage sace for later use
DB byte[,byte...] Define bytes as numeric or ASCII constants
DW word[,word...] Define words (two bytes)
const=constant (true if bit 0 is 1, otherwise false)
Error codes
-----------
D Data error (element cannot be placed in data area)
E Expression error (ill-formed expression)
L Label error
N Not implemented
O Overflow (expression too complicated to compute)
P Phase error (label has different values on each pass)
R register error (specified value not compatible with op code)
U Undefined label (label does not exist)
V Vaue error (operand improper)
Fatal errors
------------
NO SOURCE FILE PRESENT
NO DIRECTORY SPACE
SOURCE FILE NAME ERROR
SOURCE FILE READ ERROR
OUTPUT FILE WRITE ERROR
CANNOT CLOSE FILE
FILE TYPES
==========
ASC ASCII text file, usually Basic source
ASM ASseMbly langaige file (source for ASM program)
BAK BAcKup copy file (created by editor)
BAS BASic source program file, usually tokenized
COM COMmand file (transient exeuctable program)
DAT DATa file
DOC DOCument file
FOR FORtran source program file
INT INTermediate Basic program file (executable)
HEX HEXadecimal format file (for LOAD program)
LIB Library file used by macro assembler
PLI PL/I source file
PRN PRiNt file (source and object produced by ASM)
REL RELocatable file
SAV System file (V2.x)
SUB SUBmit text file executed by SUBMIT program
SYM SID symbol file
TEX TEXt formatter source file
XRF Cross reference file
$$ Temporary file
Filename - 8 characters maximum
Filetype - 3 characters maximum
Invalid filename and filetype characters
< > . , ; : = ? [ ]
DDT COMMANDS
============
DDT
DDT filename.HEX
DDT filename.COM
A sad Assemble symbolic code; start at sad
D Dump RAM to console from cad, 16 lines
D sad Dump RAM to console from sad, 16 lines
D sad,ead Dump RAM to console from sad thru ead
F sad,ead,const Fill RAM from sad thru ead with const
G Start program exec. at saved PC
G sad Start program exec. at sad
G sad,bp1 Start program exec. at sad and stop at bp1
G sad,bp1,bp2 Start program exec. at sad and stop at bp1 or bp2
G,bp1,bp2 Start program exec. at cad and stop at bp1 or bp2
G0 Jump to 0000H ==> exits DDT (equivalent to Ctrl-C)
H a,b Display hex a+b and a-b
I filename Set up FCB at 5CH for user code
I filename.typ Set up FCB at 5CH for R-command (HEX or COM file)
L Disassemble RAM from cad, 12 lines
L sad Disassemble RAM from sad, 12 lines
L sad,ead Disassemble RAM from sad thru ead
M sad,ead,nad Move RAM block from sad thru ead to nad
R Read file specified by I command to RAM
R offset at normal address + optional offset
The R command requires a previos I command
There is no W (write file) command, instead
exit DDT (by G0 or Ctrl-C) and then use SAVE
S sad Examine and optionally alter RAM, byte by byte,
starting at sad
T Trace: execute 1 instruction with register dump
T n Trace: Execute n instructions with register dump
U Untrace: same as T except that intermediate
U n steps are not displayed
X Examine register or flags, display format:
CfZfMfEfIf A=bb B=dddd D=dddd H=dddd S=dddd P=dddd inst
Xr Examine/change registers or flags
C Carry flag (0/1)
Z Zero flag (0/1)
M Sign flag (0/1)
E Parity flag (0/1)
I Aux Carry flag (0/1)
A Accumulator (0-FF)
B BC reg pair (0-FFFF)
D DE reg pair (0-FFFF)
H HL reg pair (0-FFFF)
S Stack Pointer (0-FFFF)
P Program Counter (0-FFFF)
cad = current address
nad = new address
sad = start address
ead = end address
? = error, can mean:
file cannot be opened
checksum error in HEX file
assembler(disassembler overlayed
ED COMMANDS
===========
nA Append n lines to buffer (n=0 - use haf of buffer)
B Move pointer to beginning of file
-B Move pointer to end of file
nC Move pointer forward n characters
nD Delete n characters forward
E End edit, close file, return to CP/M
nFs Find n'th occurence of string 's'
H End edit, move pointer to beginning of file
I Insert text at pointer until ^Z typed
Is Insert string at pointer
nK Kill n lines starting at pointer
nL Move pointer n lines
nMx Execute command string 'x' n times
nNs Global F-command - until end of file
O Abort ED, start over with original file
nP List next n pages of 23 lines (n=0 - current page)
Q Quit without changing input file
Rfn Read fn.LIB into buffer at current pointer
nSx^Zy Substitute string 'y for next n forward occurrences of string 'x'
nT Type n lines
U Change lower case to upper case (next entry)
V Enable internal line number generation
nW Write n lines to output file, start at beginning of buffer
nX Write next n lines to file 'X$$$$.LIB'
nZ Pause n/2 seconds (2 MHz)
n Move forward n lines
<CR> Move forward one line and type one line
- Move backward
n:x Move to n line number and perform 'x' command
:mx Perform command 'x' from current line to line m
n::mx Move to n line number and perform command 'x' from
current line to line m
note: "-" valid on all positioning and display commands
for backward movement (e.g. -nC)
HOW TO OPEN UP A NEW USER AREA
==============================
Enter PIP wait for the * prompt. Hit Return to go back to exit PIP.
Now, enter the user area, say USER 1. Type SAVE 28 PIP.COM and hit
Return (SAVE 30 PIP.COM in CP/M 3).
Now, PIP.COM is in your new user area, and you can copy any file
into your area from area 0 by typing PIP A:=<ufn>[G0] and Return.
PATCHING THE CCP TO PERFORM ONE COMMAND AT EVERY WARM BOOT
==========================================================
The CCP stars with the instructions:
JMP CCPSTART ; Start the console processor
JMP CCPCLEAR ; Clear the initial command
DB 127 ; Maximum command length
CL: DB 0 ; Current command length
DB ' ' ; 8 spaces
DB ' ' ; 8 more spaces
DB 'COPYRIGHT... ; Copyright notice
Starting at CL, patch in the command, e.g.:
CL: DB 3 ; Current command length
DB 'DIR',0 ; DIR command, NUL terminated
DB ' ' ; 4 spaces
DB ' ' ; 8 more spaces
DB 'COPYRIGHT... ; Copyright notice
and add this to the CCP image on the system tracks of your disk
(using MOVCPM, DDT and SYSTEM on most CP/M systems, or DDT amd
CPM56K.COM or CPM60K.COM on Apple CP/M). Now, after every warm boot
the CCP will execute this command (in this example a 'DIR' command)
BDOS FUNCTION CALLS
===================
Function no Value passed to BDOS Value returned in
in C reg in DE (or E) regs A or HL regs
Dec Hex
0 00 System reset -- --
1 01 Console read -- A = char
2 02 Console write E = char --
3 03 Reader read -- A = char
4 04 Punch write E = char --
5 05 List write E = char --
6 06 Direct console I/O E = FFh (input) A = char
(V2.x) E = char (output) --
7 07 Get IOBYTE -- A = IOBYTE
8 08 Set IOBYTE E = IOBYTE --
9 09 Print string DE = string addr --
string terminated by $, tabs are expanded as in func 2
10 0A Read console buffer DE = buffer addr A = #chars in buffer
buffer: 1st byte = bufsize, 2nd byte = chars input
11 0B Get console status -- A = 00(not rdy)/FF(rdy)
12 0C Lift head (V1.x) -- --
Get version (V2.x) -- HL = version no
H: 0=CP/M, 1=MP/M
L: 0=v1.4
20H-22H=v2.x
13 0D Reset disk** -- --
14 0E Select disk E = drive no --
0=A, 1=B, ...0FH=P
15 0F Open file DE = FCB addr A = dir code
16 10 Close file DE = FCB addr A = dir code
17 11 Search for first DE = FCB addr A = dir code
18 12 Search for next -- A = dir code
19 13 Delete file DE = FCB addr A = dir code
20 14 Read sequential DE = FCB addr A = ret code
21 15 Write sequential DE = FCB addr A = ret code
22 16 Create file DE = FCB addr A = dir code
23 17 Rename file DE = old FCB addr A = dir code
24 18 Get login vector -- (V1.4) HL = drive code
25 19 Get disk no -- A = curr disk no
(0-15 for A-P)
26 1A Set DMA addr DE = DMA addr --
27 1B Get alloc vector -- HL = ava
28 1C Write protect disk -- --
29 1D Get R/O vector -- HL = R/O vect
30 1E Set file attrib DE = FCB addr A = dir code
31 1F Get addr disk params -- HL = dpba
32 20 Set user code E = user code --
32 20 Get user code E = FFh A = curr user code
33 21 Read random DE = ext. FCB addr A = ret code ***
34 22 Write random DE = ext. FCB addr A = ret code ***
35 23 Compute file size DE = ext. FCB addr A = ret code
36 24 Set random record DE = ext. FCB addr A = ret code
37 25 Reset drive DE = drive vector A = 0
38 26 (unused) -- --
39 27 (unused) -- --
40 28 Write random DE = FCB addr A = ret code ***
with zero fill
dir code: directory code:
0FFH=failed (e.g. file not found, directory full)
0,1,2,3 = success: offset into current DMA buffer, which
contains a directory sector, where the FCB can be found
ret code: return code -- 0=success, non-zero=failed
* V1.4 none
** V1.4 initializes system and selects A: drive
00 - no error
01 - reading unwritten data
03 - cannot close current extent
04 - seek to unwritten extent
05 - directory overflow (write only)
06 - seek past physical end of disk
char = ASCII character
addr = address
dir = directory code
cdn = current drive number (A=0, B=1, etc)
dpba = disk parameter block address in CBIOS
Function 9: string is terminated with '