CP/M Assembler Utilities Help Page


This page is mirrored from René van Belzen's CP/M pages on The Commodore 128 Page at Tripod. The only functional changes being to remove the links not associated with CP/M.

The contents are either (C) Copyright Burton Craddock 2007 or are derivative or direct works of their various authors to which the respective Copyrights apply. It is provided in the hope that it will be interesting or useful or both, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. In particular, Bill Buckels has no warranty obligations or liability resulting from its use in any way whatsoever.

Return to The C128 and C64 CP/M 80 Links Page

[ DUMP / GENCOM / HEXCOM / LIB / LINK / MAC / RMAC / SID / XREF ]

DUMP

Syntax:

DUMP filespec

Explanation:

DUMP displays the contents of a file in hexadecimal and ASCII format.

Example:

A>DUMP ABC.TEX

GENCOM

Syntax:

GENCOM COM-filespec RSX-filespec ... [LOADER NULL SCB=(offset,value)]

Explanation:

The GENCOM command creates a special COM file with attached RSX files. The GENCOM command can also restore a previously GENCOMed file to the original COM file without the header and RSX's. GENCOM can also attach header records to COM files.

GENCOM
OPTIONS

LOADER
sets a flag to keep the program loader active.
NULL
indicates that only RSX files are specified. GENCOM creates a dummy COM file for the RSX files. The output COM filename is taken from the filename of the first RSX-filespec.
SCB=(offset,value)
sets the System Control Block from the program by using the hex values specified by (offset,value).

GENCOM
EXAMPLES

A>GENCOM MYPROG PROG1 PROG2

Generates a new COM file MYPROG.COM with attached RSX's PROG1 and PROG2.

A>GENCOM PROG1 PROG2 [NULL]

Creates a COM file PROG1.COM with RSX's PROG1 and PROG2.

A>GENCOM MYPROG

GENCOM takes MYPROG.COM, strips off the header and deletes all attached RSX's to restore it to its original COM format.

A>GENCOM MYPROG PROG1 PROG2

GENCOM looks at the already-GENCOMed file MYPROG.COM to see if PROG1.RSX and PROG2.RSX are already attached RSX files in the module. If either one is already attached, GENCOM replaces it with the new RSX module. Otherwise, GENCOM appends the specified RSX files to the COM file.


HEXCOM

Syntax:

HEXCOM filename

Explanation:

The HEXCOM Command generates a command file (filetype .COM) from a .HEX input file. It names the output file with the same filename as the input file but with filetype .COM. HEXCOM always looks for a file with filetype .HEX.

Example:

A>HEXCOM B:PROGRAM

Generates a command file PROGRAM.COM from the input hex file PROGRAM.HEX.


LIB

Syntax:

LIB filespec[IMPD]
LIB filespec[IMP]=filespecmodifier,filespecmodifier ...

Explanation:

A library is a file that contains a collection of object modules. Use the LIB utility to create libraries, and to append, replace, select or delete modules from an existing library. Use LIB to obtain information about the contents of library files.

LIB creates and maintains library files that contain object modules in Microsoft REL file format. These modules are produced by Digital Research's relocatable macro-assembler program, RMAC, or any other language translator that produces modules in Microsoft REL file format.

You can use LINK-80 to link the object modules contained in a library to other object files. LINK-80 automatically selects from the library only those modules needed by the program being linked, and then forms an executable file with a filetype of COM.

LIB
OPTIONS

I
The INDEX option creates an indexed library file of type .IRL. LINK-80 searches faster on indexed libraries than on non-indexed libraries.
M
The MODULE option displays module names.
P
The PUBLICS option displays module names and the public variables for the new library file.
D
The DUMP option displays the contents of object modules in ASCII form.

LIB
MODIFIERS

Use modifiers in the command line to instruct LIB to delete, replace, or select modules in a library file. Angle brackets enclose the modules to be deleted or replaced. Parentheses enclose the modules to be selected.

LIB Modifiers

Delete
<module=>
Replace
<module=filename.REL>
If module name and filename are the same this shorthand can be used:
<filename>
Select
(modFIRST-modLAST,mod1,mod2,...,modN)

LIB
EXAMPLES

A>LIB TEST4[P]

Displays all modules and publics in TEST4.REL.

A>LIB TEST5[P]=FILE1,FILE2

Creates TEST5.REL from FILE1.REL and FILE2.REL and displays all modules and publics in TEST5.REL.

A>LIB TEST=TEST1(MOD1,MOD4), TEST2(C1-C4,C6)

Creates a library file TEST.REL from modules in two source files. TEST1.REL contributes MOD1 and MOD4. LIB extracts modules C1, C4, and all the modules located between them, as well as module C6 from TEST2.REL.

A>LIB FILE2=FILE3<MODA=>

Creates FILE2.REL from FILE3.REL, omitting MODA which is a module in FILE3.REL.

A>LIB FILE6=FILE5<MODA=FILEB.REL>

Creates FILE6.REL from FILE5.REL, FILEB.REL replaces MODA.

A>LIB FILE6=FILE5<THISNAME>

Module THISNAME is in FILE5.REL. When LIB creates FILE6.REL from FILE5.REL the file THISNAME.REL replaces the similarly named module THISNAME.

A>LIB FILE1[I]=B:FILE2(PLOTS,FIND,SEARCH-DISPLAY)

Creates FILE1.IRL on drive A from the selected modules PLOTS, FIND, and modules SEARCH through the module DISPLAY, in FILE2.REL on drive B.


LINK

Syntax:

LINK d:filespec,[options]=filespec[options],...

Explanation:

LINK combines relocatable object modules such as those produced by RMAC and PL/I-80 into a .COM file ready for execution. Relocatable files can contain external references and publics. Relocatable files can reference modules in library files. LINK searches the library files and includes the referenced modules in the output file. See the CP/M 3 Programmer's Utilities Guide for a complete description of LINK-80.

LINK
OPTIONS

Use LINK option switches to control execution parameters. Link options follow the file specifications and are enclosed within square brackets. Multiple switches are separated by commas.

LINK-80 Options

A
Additional memory; reduces buffer space and writes temporary data to disk
B
BIOS link in banked CP/M 3 system.
  1. Aligns data segment on page boundary.
  2. Puts length of code segment in header.
  3. Defaults to .SPR filetype.
Dhhhh
Data origin; sets memory origin for common and data area
Gn
Go; set start address to label n
Lhhhh
Load; change default load address of module to hhhh. Default 0100H
Mhhhh
Memory size; Define free memory requirements for MP/M modules.
NL
No listing of symbol table at console
NR
No symbol table file
OC
Output .COM command file. Default
OP
Output .PRL page relocatable file for execution under MP/M in relocatable segment
OR
Output .RSP resident system process file for execution under MP/M
OS
Output .SPR system page relocatable file for execution under MP/M
Phhhh
Program origin; changes default program origin address to hhhh. Default is 0100H.
Q
Lists symbols with leading question mark
S
Search preceding file as a library
$Cd
Destination of console messages
d can be X (console), Y (printer), or Z (zero output). Default is X.
$Id
Source of intermediate files; d is disk drive A-P. Default is current drive.
$Ld
Source of library files; d is disk drive A-P. Default is current drive.
$Od
Destination of of object file; d can be Z or disk drive A-P. Default is to same drive as first file in the LINK-80 command.
$Sd
Destination of symbol file; d can be Y or Z or disk drive A-P. Default is to same drive as first file in LINK-80 command.

LINK EXAMPLES

A>LINK b:MYFILE[NR]

LINK-80 on drive A uses as input MYFILE.REL on drive B and produces the executable machine code file MYFILE.COM on drive B. The [NR] option specifies no symbol table file.

A>LINK m1,m2,m3

LINK-80 combines the separately compiled files m1, m2, and m3, resolves their external references, and produces the executable machine code file m1.COM.

A>LINK m=m1,m2,m3

LINK-80 combines the separately compiled files m1, m2, and m3 and produces the executable machine code file m.COM.

A>LINK MYFILE,FILE5[s]

The [s] option tells LINK-80 to search FILE5 as a library. LINK-80 combines MYFILE.REL with the referenced subroutines contained in FILE5.REL on the default drive A and produces MYFILE.COM on drive A.


MAC

Syntax:

MAC filename $options

Explanation:

MAC, the CP/M 3 macro assembler, reads assembly language statements from a file of type .ASM, assembles the statements, and produces three output files with the input filename and filetypes of .HEX, .PRN, and .SYM. Filename.HEX contains INTEL hexadecimal format object code. Filename.PRN contains an annotated source listing that you can print or examine at the console. Filename.SYM contains a sorted list of symbols defined in the program.

MAC
EXAMPLES

A>MAC SAMPLE

A>MAC SAMPLE $PB AA HB SX

MAC
OPTIONS

Use options to direct the input and output of MAC. Use a letter with the option to indicate the source and destination drives, and console, printer, or zero output. Valid drive names are A thru O. X, P and Z specify console, printer, and zero output, respectively.

Assembly Options That Direct Input/Output

A
source drive for .ASM file (A-O)
H
destination drive for .HEX file (A-O, Z)
L
source drive for macrolibrary .LIB files called by the MACLIB statement.
P
destination drive for .PRN file (A-O, X, P, Z)
S
destination drive for .SYM file

Assembly Options That Modify Contents Of Output File

+L
lists input lines read from macrollibrary .LIB files
-L
suppresses listing (default)
+M
lists all macro lines as they are processed during assembly
-M
suppresses all macro lines as they are read during assembly
*M
lists only hex generated by macro expansions
+Q
lists all LOCAL symbols in the symbol list
-Q
suppresses all LOCAL symbols in the symbol list (default)
+S
appends symbol file to print file
-S
suppresses creation of symbol file
+1
produces a pass 1 listing for macro debugging in .PRN file
-1
suppress listing on pass 1 (default)

RMAC

Syntax:

RMAC filespec $Rd $Sd $Pd

Explanation:

RMAC, a relocatable macro assembler, assembles .ASM files of into .REL files that you can link to create .COM files.

RMAC
OPTIONS

RMAC options specify the destination of the output files. Replace d with the destination drive letter for the output files.

Option d=output option
R
drive for REL file (A-O, Z)
S
drive for SYM file (A-O, X, P, Z)
P
drive for PRN file (A-O, X, P, Z)
A-O
specifies drive A-O.
X
means output to the console.
P
means output to the printer.
Z
means zero output.

RMAC
EXAMPLE

A>RMAC TEST $PX SB RB

Assembles the file TEST.ASM from drive A, sends the listing file (TEST.PRN) to the console, puts the symbol file (TEST.SYM) on drive B and puts the relocatable object file (TEST.REL) on drive B.


SID

Syntax:

SID pgm-filespec,sym-filespec

Explanation:

The SID symbolic debugger allows you to monitor and test programs developed for the 8080 microprocessor. SID supports real-time breakpoints, fully monitored execution, symbolic disassembly, assembly, and memory display and fill functions. SID can dynamically load SID utility programs to provide traceback and histogram facilities.

SID
COMMANDS

Command
Meaning
As
(Assemble)
Enter assembly language statements
s is the start address
Csb,d
(Call)
Call to memory location from SID
s is the called address
b is the value of the BC register
pair d is the value of the DE register pair
DWs,f
(Display)
Display memory in hex and ASCII
W is a 16-bit word format
s is the start address
f is the finish address
Epgm-filespec
(Load)
Load program and symbol table, sym-filespec, for execution
E*sym-filespec
(Load)
Load a symbol table file
Fs,f,d
(Fill)
Fill memory with constant value
s is the start address
f is the finish address
d is an eight-bit data item
Gp,a,b
(Go)
Begin Execution
p is a start address
a is a temporary breakpoint
H
(Hex)
Displays all symbols with addresses in Hex
H.a
Displays hex, decimal, and ASCII values of a where
a is a symbolic expression
Ha,b
Computes hex sum and difference of a and b where
a and b are symbolic expressions
Icommand tail
(Input)
Input CCP command line
Ls,f
(List)
List 8080 mnemonic instructions
s is the start address
f is the finish address
Ms,h,d
(Move)
Move Memory Block
s is the start address
h is the high address of the block
d is the destination start address
Pp,c
(Pass)
Pass point set, reset, and display
p is a permanent breakpoint address
c is initial value of pass counter
Rfilespec,d
(Read)
Read Code/Symbols
d is an offset to each address
SWs
(Set)
Set Memory Values
s is address where value is sent
W is 16 bit word
Tn,c
(Trace)
Trace Program Execution
n is the number of program steps
c is the utility entry address.
TWn,c
(Trace)
Trace Without Call
W instructs SID not to trace subroutines
n is the number of program steps
c is the utility entry address
UWn,c
(Untrace)
Monitor Execution without Trace
n is the number of program steps
c is the utility entry address
W instructs SID not to trace subroutines
V
(Value)
Display the value of the next available location in memory (NEXT), the next location after the largest file read in (MSZE), the current value of the Program counter (PC), and the address of the end of available memory (END)
Wfilespec,s,f
(Write)
Write the contents of a contiguous block of memory to filespec.
f is finish address
Xfr
(Examine)
Examine/alter CPU state.
f is flag bit C,Z,M,E or I.
r is register A,B,D,H,S or P.

SID
EXAMPLES

A>SID

CP/M 3 loads SID from drive A into memory. SID displays the # prompt when it is ready to accept commands.

A>B:SID SAMPLE.HEX

CP/M 3 loads SID and the program file SAMPLE.HEX into memory from drive B.

SID
UTILITIES

SID utilities, HIST.UTL and TRACE.UTL are special programs that operate with SID to provide additional debugging facilities. The mechanisms for system initialization, data collection, and data display are described in the CP/M SID User's Guide.

The HIST utility creates a histogram (bar graph) showing the relative frequency of execution of code within selected program segments of the test program. The HIST utility allows you to monitor those sections of code that execute most frequently.

The TRACE utility obtains a backtrace of the instructions that led to a particular breakpoint address in a program under test. You can collect the addresses of up to 256 instructions between pass points in U or T modes.


XREF

Syntax:

XREF d: filename $P

Explanation:

XREF provides a cross-reference summary of variable usage in a program. XREF requires the .PRN and .SYM files produced by MAC or RMAC for input to the program. The SYM and PRN files must have the same filename as the filename in the XREF command tail. XREF outputs a file of type .XRF.

Examples:

A>XREF b:MYPROG

A>XREF b:MYPROG $P

Go to Top of Document