.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