.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






