mirror of
https://github.com/SEPPDROID/Digital-Research-Source-Code.git
synced 2025-10-23 08:24:18 +00:00
675 lines
16 KiB
TeX
675 lines
16 KiB
TeX
.bp
|
|
.cs 5
|
|
.mt 5
|
|
.mb 6
|
|
.pl 66
|
|
.ll 65
|
|
.po 10
|
|
.hm 2
|
|
.fm 2
|
|
.he
|
|
.ft All Information Presented Here is Proprietary to Digital Research
|
|
.ce
|
|
.sh
|
|
Section 7
|
|
.sp
|
|
.ce
|
|
.sh
|
|
Programming Utilities
|
|
.qs
|
|
.he CP/M-8000 Programmer's Guide 7.1 Archive Utility
|
|
.ix programming utilities
|
|
.ix AR68
|
|
.ix DUMP
|
|
.ix XDUMP
|
|
.ix archive (AR8K) utility, syntax
|
|
.sp 2
|
|
.pp 5
|
|
CP/M-8000 supports five programming utilities: Archive
|
|
(AR8K), DUMP, and object-file dump (XDUMP).
|
|
AR8K allows you to create and modify libraries. DUMP displays the
|
|
contents of files in hexadecimal and ASCII notation.
|
|
XDUMP displays the contents of object files in a variety of formats.
|
|
.qu
|
|
This section describes each of these utilities in a
|
|
separate subsection.
|
|
.sp 2
|
|
.tc 7.1 Archive Utility
|
|
.he CP/M-8000 Programmer's Guide 7.1 Archive Utility
|
|
.sh
|
|
7.1 Archive Utility
|
|
.qs
|
|
.pp
|
|
.ix AR8K
|
|
.ix Archive Utility
|
|
The Archive Utility, AR8K, creates a library or replaces, adds,
|
|
deletes, lists, or extracts object modules in an existing
|
|
library. AR8K can be used on the C Run-Time Library distributed
|
|
with CP/M-8000 and documented in the \c
|
|
.ul
|
|
C Language Reference Manual \c
|
|
.qu
|
|
for the Z8000 microprocessor.
|
|
================= CHECK AGAINST AR8K DOCUMENT ============
|
|
.sp 2
|
|
.tc 7.1.1 AR8K Syntax
|
|
.sh
|
|
7.1.1 AR8K Syntax
|
|
.qs
|
|
.ix invoking AR8K
|
|
.pp
|
|
To invoke AR8K, specify the components of the command line shown
|
|
below. Optional components are enclosed in square brackets ([]).
|
|
.sp
|
|
AR8K DRTWX[AV][F D:] [OPMOD] ARCHIVE OBMOD1 [OBMOD2...][>filespec]
|
|
.qs
|
|
.sp
|
|
.qi
|
|
You can specify multiple object modules in a command line
|
|
provided the command line does not exceed 127 bytes. The
|
|
delimiter character between components consists of one or more
|
|
spaces.
|
|
.sp 2
|
|
.ce
|
|
.sh
|
|
Table 7-1. AR8K Command Line Components
|
|
.qs
|
|
.sp
|
|
.in 5
|
|
.nf
|
|
Component Meaning
|
|
.sp
|
|
.fi
|
|
.ll 60
|
|
.in 18
|
|
.ti -13
|
|
AR8K
|
|
.sp
|
|
invokes the Archive Utility. However, if you
|
|
specify only the AR8K command, AR8K returns the command line
|
|
syntax and the system prompt as shown below.
|
|
.sp
|
|
A>AR8K
|
|
.sp 0
|
|
.nf
|
|
usage: AR8K DRTWX[AV][F D:] [OPMOD] ARCHIVE OBMOD1 [OBMOD2...][>filespec]
|
|
.sp
|
|
.fi
|
|
A>
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-1. (continued)
|
|
.qs
|
|
.sp
|
|
.in 5
|
|
.nf
|
|
Component Meaning
|
|
.sp
|
|
.fi
|
|
.ll 60
|
|
.in 18
|
|
.ti -13
|
|
DRTWX
|
|
.sp
|
|
indicates you must specify one of these letters as
|
|
an AR8K command. Each of these one-letter commands and
|
|
their options are described in Section 7.1.3.
|
|
.sp 2
|
|
.ti -13
|
|
AV
|
|
.sp
|
|
indicates you can specify one or both of these
|
|
one-letter options. These options are described with the commands
|
|
in Section 7.1.3.
|
|
.sp 2
|
|
.ti -13
|
|
OPMOD
|
|
.sp
|
|
is an object module within the library that you specify.
|
|
The OPMOD parameter indicates the position in which additional object modules
|
|
reside when you incorporate modules in the library and specify the
|
|
A option.
|
|
.sp 2
|
|
.ti -13
|
|
F D:
|
|
.sp
|
|
specifies the drive on which the temporary file
|
|
created by AR8K resides. The variable D is the drive select
|
|
code; it must be followed by a colon (:). AR8K creates a
|
|
temporary file called AR8K.TMP that AR8K uses as a scratchpad
|
|
area.
|
|
.sp 2
|
|
.ti -13
|
|
ARCHIVE
|
|
.sp
|
|
is the file specification of the library.
|
|
.sp 2
|
|
.ti -13
|
|
OBMOD1 [OBMOD2 ...]
|
|
.sp
|
|
indicates one or more object modules in a library that AR8K
|
|
deletes, adds, replaces, or extracts.
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-1. (continued)
|
|
.qs
|
|
.sp
|
|
.in 5
|
|
.nf
|
|
Component Meaning
|
|
.sp
|
|
.fi
|
|
.ll 60
|
|
.in 18
|
|
.ti-13
|
|
>filespec
|
|
.sp
|
|
redirects the output to the file specification that you specify,
|
|
rather than sending the output to the standard output device,
|
|
which is usually the console device (CONSOLE). You can redirect
|
|
the output for any of the AR8K commands described in Section 7.1.3.
|
|
.in 0
|
|
.ll 65
|
|
.sp 2
|
|
.tc 7.1.2 AR8K Operation
|
|
.sh
|
|
7.1.2 AR8K Operation
|
|
.qs
|
|
.ix AR8K operation
|
|
.pp
|
|
AR8K sequentially parses the command line only once. AR8K
|
|
searches for, inserts, replaces, or deletes object modules in
|
|
the library in the sequence in which you specify them in the
|
|
command line. Section 7.1.3 describes each of the commands
|
|
AR8K supports.
|
|
.pp
|
|
When AR8K processes a command, it creates a temporary file called AR8K.TMP.
|
|
AR8K creates and uses AR8K.TMP when it processes AR8K commands. After
|
|
the operation is complete AR8K erases AR8K.TMP. However, depending on when
|
|
an error occurs, AR8K.TMP is not always erased. If this occurs, erase
|
|
AR8K.TMP with the ERA command and refer to Appendix E for error messages
|
|
output by AR8K.
|
|
.sp 2
|
|
.tc 7.1.3 AR8K Commands and Options
|
|
.sh
|
|
7.1.3 AR8K Commands and Options
|
|
.qs
|
|
.ix AR8K commands
|
|
.ix AR8K options
|
|
.ix commands, AR8K
|
|
.ix options, AR8K
|
|
.pp
|
|
This section describes AR8K commands and their options. Examples
|
|
illustrate the effect and interaction between each command and the
|
|
options it supports.
|
|
.sp 2
|
|
.ce
|
|
.sh
|
|
Table 7-2. AR8K Commands and Options
|
|
.qs
|
|
.in 5
|
|
.ll 60
|
|
.sp
|
|
.nf
|
|
Command/Option Meaning
|
|
.fi
|
|
.in 23
|
|
.ti -12
|
|
.sp
|
|
D deletes from the library one or more object modules
|
|
specified in the command. You can specify
|
|
the V option for this command.
|
|
.ix D command (AR8K)
|
|
.sp 2
|
|
.ti -12
|
|
V lists the modules in the library and indicates which modules
|
|
are retained and deleted by the D command. The V option precedes
|
|
modules retained in the library with the lower-case letter c and modules
|
|
deleted from the library with the lower-case letter d as shown below.
|
|
.ix V option (AR8K)
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-2. (continued)
|
|
.qs
|
|
.in 5
|
|
.ll 60
|
|
.sp
|
|
.nf
|
|
Command/Option Meaning
|
|
.fi
|
|
.sp
|
|
.in 23
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
AR8K DV MYRAH.ARC ORC.O
|
|
.qs
|
|
.sp 0
|
|
c red.o
|
|
c blue.o
|
|
d orc.o
|
|
c white.o
|
|
.sp
|
|
A>
|
|
.fi
|
|
.sp
|
|
The D command deletes the module ORC.O from the library MYRAH.ARC.
|
|
In addition to listing the modules in the library, the V option
|
|
indicates which modules are retained and deleted.
|
|
.sp 2
|
|
.ix R command (AR8K)
|
|
.ti -12
|
|
R creates a library when the one specified in the command line
|
|
does not exist or, replaces or adds object modules to an existing
|
|
library. You must specify one or more object modules.
|
|
.pp
|
|
You can replace more than one object module in the library by
|
|
specifying their module names in the command line. However, when the
|
|
library contains more than one module with the same name, AR8K
|
|
replaces only the first module it finds that matches the one
|
|
specified in the command line. AR8K replaces modules
|
|
already in the library only if you specify their names prior to
|
|
the names of new modules to be added to the library. For
|
|
example, if you specify the name of a module that you want
|
|
replaced after the name of a module that you are adding to the
|
|
library, AR8K adds both modules to the end of the library.
|
|
.pp
|
|
By default, the R command adds new modules to the end of the
|
|
library. The R command adds an object module to a library if:
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-2. (continued)
|
|
.qs
|
|
.in 5
|
|
.ll 60
|
|
.sp
|
|
.nf
|
|
Command/Option Meaning
|
|
.fi
|
|
.sp
|
|
.in 23
|
|
.in 28
|
|
.ti -2
|
|
o The object module does not already exist in the
|
|
library.
|
|
.sp
|
|
.ti -2
|
|
o You specify the A option in the command line.
|
|
.sp
|
|
.ti -2
|
|
o The name of a module follows the name of module
|
|
that does not already exist in the library.
|
|
.in 23
|
|
.pp
|
|
The A option indicates
|
|
where AR8K adds modules to the library. You specify the relative
|
|
position by including the OPMOD parameter with the A option.
|
|
.pp
|
|
In addition to the A option, the R command also
|
|
supports the V option, which lists the modules in the library and
|
|
indicates the result of the operation performed on the library.
|
|
All options are described below. Examples illustrate their use.
|
|
.sp 2
|
|
.ix A command (AR8K)
|
|
.ti -12
|
|
A adds one or more object modules following the module
|
|
specified in the command line as shown below.
|
|
.sp
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
AR8K RAV SDAV.O MYRAH.ARC WORK.O MAIL.O
|
|
.qs
|
|
.sp 0
|
|
c much.o
|
|
c sdav.o
|
|
a work.o
|
|
a mail.o
|
|
c less.o
|
|
.fi
|
|
.sp
|
|
The RAV command adds the object modules WORK.O and
|
|
MAIL.O after the module SDAV.O in the library MYRAH.ARC.
|
|
The V option, described below, lists all the modules in the
|
|
library. New modules are preceded by the lower-case letter a
|
|
and existing modules are preceded by the lower-case letter c.
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-2. (continued)
|
|
.qs
|
|
.in 5
|
|
.ll 60
|
|
.sp
|
|
.nf
|
|
Command/Option Meaning
|
|
.fi
|
|
.sp
|
|
.in 23
|
|
.ti -12
|
|
V lists the object modules that the R command replaces or adds.
|
|
.ix V option (AR8K)
|
|
.sp
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
AR8K RV JNNK.MAN NAIL.O WRENCH.O
|
|
.qs
|
|
.sp 0
|
|
c saw.o
|
|
c ham.o
|
|
r nail.o
|
|
c screw.o
|
|
a wrench.o
|
|
.sp
|
|
A>
|
|
.fi
|
|
.sp
|
|
The R command replaces the object module NAIL.O and adds the
|
|
module WRENCH.O to the library JNNK.MAN. The V option lists
|
|
object modules in the library and indicates which modules are
|
|
replaced or added. Each object module that is replaced is
|
|
preceded with the lower-case letter r and each one that is added
|
|
is preceded with the lower-case letter a.
|
|
.sp 2
|
|
.ix T command (AR8K)
|
|
.ti -12
|
|
T requests AR8K print a table of contents or a list of
|
|
specified modules in the library. The T command prints a table
|
|
of contents of all modules in the library only when you do not
|
|
specify names of object modules in the command line.
|
|
.sp 2
|
|
.ti -12
|
|
V displays the size of each file in the table of contents as
|
|
shown in the example below.
|
|
.sp
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
AR8K TV WINE.BAD
|
|
.qs
|
|
.sp 0
|
|
rw-rw-rw- 0/0 6818 rose.o
|
|
rw-rw-rw- 0/0 2348 white.o
|
|
rw-rw-rw- 0/0 396 red.o
|
|
.sp
|
|
A>
|
|
.fi
|
|
|
|
.sp 2
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-2. (continued)
|
|
.qs
|
|
.in 5
|
|
.ll 60
|
|
.sp
|
|
.nf
|
|
Command/Option Meaning
|
|
.fi
|
|
.sp
|
|
.in 23
|
|
The T command prints a table of contents in the library WINE.BAD.
|
|
In addition to listing the modules in the library, the V option
|
|
indicates the size of each module. The character string rw-rw-rw-
|
|
0/0 that precedes the module size is meaningless for CP/M-8000.
|
|
However, if the file is transferred to a UNIX \ \ system, the
|
|
character string denotes the file protection and file
|
|
owner. The size
|
|
specified by the decimal number that precedes the object module name
|
|
indicates the number of bytes in the module.
|
|
.ix V option (AR8K)
|
|
.sp 2
|
|
.ix W command (AR8K)
|
|
.ti -12
|
|
W writes a copy of an object module in the library to the
|
|
>filespec parameter specified in the command line. This command
|
|
allows you to extract a copy of a module from a library and
|
|
rename the copy when you write it to another disk, as shown below.
|
|
For this command, the >filespec parameter is not optional.
|
|
.sp
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
AR8K W GO.ARC NOW.O >B:NEWNAME.O
|
|
.qs
|
|
.fi
|
|
.sp
|
|
The W command writes a copy of
|
|
the object module NOW.O from the library GO.ARC to the
|
|
file NEWNAME.O on drive B.
|
|
.sp 2
|
|
.ti -12
|
|
X extracts a copy of one or more object modules from a library
|
|
and writes them to the default disk. If no object modules are
|
|
specified in the command line, the X command extracts a copy of
|
|
each module in the library.
|
|
.bp
|
|
.in 0
|
|
.ll 65
|
|
.ce
|
|
.sh
|
|
Table 7-2. (continued)
|
|
.qs
|
|
.in 5
|
|
.ll 60
|
|
.sp
|
|
.nf
|
|
Command/Option Meaning
|
|
.fi
|
|
.sp
|
|
.in 23
|
|
.ix X command (AR8K)
|
|
.ti -12
|
|
V Lists only those modules the X command extracts from the
|
|
library. It precedes each extracted module with the lower-case
|
|
letter as shown below.
|
|
.ix V option (AR8K)
|
|
.sp
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
AR8K XV JNNK.MAN SAW.O HAM.O SCREW.O
|
|
.qs
|
|
.sp 0
|
|
x saw.o
|
|
x ham.o
|
|
x screw.o
|
|
.fi
|
|
.sp
|
|
The V option with the X command lists only the modules SAW.O,
|
|
HAM.O, and SCREW.O that the X command extracts from the library
|
|
JNNK.MAN and precedes each of these modules with the lower-case
|
|
letter x.
|
|
.tc 7.1.4 Errors
|
|
.sp 2
|
|
.in 0
|
|
.ll 65
|
|
.sh
|
|
7.1.4 Errors
|
|
.ix AR8K errors
|
|
.ix errors, AR8K
|
|
.qs
|
|
.pp
|
|
When AR8K incurs an error during an operation, the
|
|
operation is not completed. The original library is not modified
|
|
if the operation would have modified the library. Thus, no modules
|
|
in the library are deleted, replaced, added, or extracted.
|
|
Refer to Appendix E for error messages output by AR8K.
|
|
.pp
|
|
When you specify the >filespec parameter in the command line to
|
|
redirect the output and one or more errors occur, the error
|
|
messages are sent to the output file. Thus, you cannot detect the
|
|
errors without displaying or printing the file to which the
|
|
output was sent. If the contents of the output
|
|
file is an object file (see the W command), you must use the
|
|
DUMP Utility described in Section 7.2 to read any error messages.
|
|
.sp 2
|
|
.he CP/M-8000 Programmer's Guide 7.2 DUMP Utility
|
|
.tc 7.2 DUMP Utility
|
|
.sh
|
|
7.2 DUMP Utility
|
|
.qs
|
|
.ix DUMP utility, invoking
|
|
.pp 5
|
|
The DUMP Utility (DUMP) displays the contents of a CP/M file in both
|
|
hexadecimal and ASCII notation. You can use DUMP to display any CP/M file
|
|
regardless of the format of its contents (binary data, ASCII text, an
|
|
executable file).
|
|
=================== THIS IS PROBABLY OK ===============
|
|
.sp 2
|
|
.tc 7.2.1 Invoking DUMP
|
|
.sh
|
|
7.2.1 Invoking DUMP
|
|
.qs
|
|
.ix invoking DUMP
|
|
.pp
|
|
Invoke DUMP by entering a command in the following format.
|
|
.sp
|
|
.ti 8
|
|
DUMP [ -sxxxx ] filename1 [ >filename2 ]
|
|
.bp
|
|
.ce
|
|
.sh
|
|
Table 7-3. DUMP Command Line Components
|
|
.qs
|
|
.ll 60
|
|
.in 5
|
|
.nf
|
|
.sp
|
|
Component Meaning
|
|
.fi
|
|
.sp
|
|
.in 20
|
|
.ti -15
|
|
-sxxxx xxxx is an optional offset (in hexadecimal) into the file.
|
|
If specified, DUMP starts dumping the contents of the file from the
|
|
byte-offset xxxx and continues until it displays the contents of the entire
|
|
file. By default, DUMP starts dumping the contents of the file from the
|
|
beginning of the file until it dumps the contents of the entire file.
|
|
.sp
|
|
.ti -15
|
|
filename1 is the name of the file you want to dump.
|
|
.sp
|
|
.ti -15
|
|
>filename2 the greater than sign (>) followed by a filename or
|
|
logical device optionally redirects
|
|
the output of DUMP. You can specify
|
|
any valid CP/M specification, or one of the logical device names CON:
|
|
(console) or LST: (list device). If you do not specify this optional
|
|
parameter, DUMP sends its output to the console.
|
|
.in 0
|
|
.ll 65
|
|
.sp 2
|
|
.tc 7.2.2 DUMP Output
|
|
.sh
|
|
7.2.2 DUMP Output
|
|
.qs
|
|
.ix DUMP output
|
|
.pp
|
|
DUMP sends the output to the console (or to a file or device, if
|
|
specified), 8 words per line, in the following format:
|
|
.sp 2
|
|
.nf
|
|
rrrr oo (ffffff): hhhh hhhh hhhh hhhh hhhh hhhh hhhh hhhh *aaaaaaaaaaaaaaaa*
|
|
.fi
|
|
.sp 2
|
|
.ce
|
|
.sh
|
|
Table 7-4. DUMP Output Components
|
|
.qs
|
|
.sp
|
|
.in 5
|
|
.ll 60
|
|
.nf
|
|
Component Meaning
|
|
.fi
|
|
.sp
|
|
.in 20
|
|
.ti -15
|
|
rrrr is the record number (CP/M records are 128 bytes)
|
|
of the current line of the display.
|
|
.sp
|
|
.ti -15
|
|
oo is the offset (in hex bytes) from the beginning of
|
|
the CP/M record.
|
|
.sp
|
|
.ti -15
|
|
ffffff is the offset (in hex bytes) from the beginning of
|
|
the file.
|
|
.sp
|
|
.mb 5
|
|
.fm 1
|
|
.ti -15
|
|
hhhh is the contents of the file displayed in hexadecimal.
|
|
.sp
|
|
.ti -15
|
|
aaaaaaaa is the contents of the file displayed as ASCII
|
|
characters. If any character is not representable in
|
|
ASCII, it is diplayed as a period (.).
|
|
.in 0
|
|
.ll 65
|
|
.bp
|
|
.tc 7.2.3 DUMP Examples
|
|
.sh
|
|
7.2.3 DUMP Examples
|
|
.qs
|
|
.sp 2
|
|
An example of the DUMP Utility is shown below. The example shows
|
|
the contents of a command file that contains both binary and ASCII
|
|
information.
|
|
.sp
|
|
.nf
|
|
A>\c
|
|
.sh
|
|
dump dump.Z8K
|
|
.qs
|
|
.sp
|
|
0000 00 (000000): 601a 0000 1b34 0000 011d 0000 0e5e 0000 *`....4.......^..*
|
|
0000 10 (000010): 0000 0000 0000 0000 0900 ffff 6034 4320 *............`4C *
|
|
0000 20 (000020): 5275 6e74 696d 6520 436f 7079 7269 6768 *Runtime Copyrigh*
|
|
0000 30 (000030): 7420 3139 3832 2062 7920 4469 6769 7461 *t 1982 by Digita*
|
|
0000 40 (000040): 6c20 5265 7365 6172 6368 2056 3031 2c30 *l Research V01.0*
|
|
0000 50 (000050): 3320 206f 0004 2268 0018 2649 d3e8 001c *3 o.."h..&ISh..*
|
|
|
|
. . . . (and so on) . . .
|
|
.sp 2
|
|
.fi
|
|
.he CP/M-8000 Programmer's Guide 7.3 Relocation Utility
|
|
.tc 7.3 XDUMP Utility
|
|
.sh
|
|
7.3 XDUMP Utility
|
|
.ix XDUMP utility
|
|
.pp 5
|
|
============== INSERT XDUMP DOCUMENT HERE ==================
|
|
.sp 2
|
|
.ce
|
|
End of Section 7
|
|
.bp
|
|
.he CP/M-8000 Programmer's Guide End of Section 7
|
|
.sp 50
|
|
.nx eight
|
|
|
|
|
|
|
|
|
|
|
|
|