

















MACPAK" (Object File Editing Utility)

Copyright @ 1983 by Lou Witt



Lou Witt P.O.Box 2135 - Sanford, FL 32772-2135                   

(305) 322-4675

                             +IMPORTANT NOTICE+

Lou Witt shall have no liability or responsibility to the customer or any other person or entity with respect to any liability, loss or damage caused or alleged to be caused directly or indirectly by any Lou Witt product, including but not limited to any interruption of service, loss of business or anticipatory profits or consequential damages resulting from the use of this or any other Lou Witt product.

While reasonable efforts have been taken in the preparation of this manual to assure its accuracy, Lou Witt & Guy Omer  assumes no liability resulting from any errors or omissions in this manual, or from the use of the information contained herein.

+GUARANTEE+

Should any Lou Witt program be unreadable or damaged, Lou Witt will replace it upon return of the defective product along with proof of purchase within 90 days of the date of purchase.

There are no other warranties, expressed or implied, including the warranties of merchantability or fitness for a particular purpose.


+COPYRIGHT 1983 BY Lou Witt Corporation. All Rights Reserved.+

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical or photocopying, recording, or otherwise without written permission from  Lou Witt. Printed in USA.

MacPak is copyrighted under United States Copyright laws by Lou Soft. It is against the law to copy MacPak for any purpose other than personal convenience.



+TRADEMARKS USED IN THIS MANUAL+

	DOSPLUS		MICRO-SYSTEMS SOFTWARE, INC.
	LDOS		LOGICAL SYSTEMS, INC.
	MACPAK		WITTSOFT CORP.
	NEWDOS80	APPARAT,INC.
	TRS80 & TRSDOS	TANDY CORP.
	WIBASIC		WITTSOFT CORP.


+ * MACPAK INDEX *+


MacPak Disk Format.................................................. 4
Disk Operating System Compatability................................. 4
MacPak Development.................................................. 4
Execution Instructions.............................................. 5
General Information................................................. 5
Function Descriptions............................................... 5

Menu Commands....................................................... 6
	<1> Zap..................................................... 6
	<2> Patch................................................... 7
	<3> Move.................................................... 7
	<4> Merge................................................... 8
	<5> Map..................................................... 9
	<6> List.................................................... 9
	<7> Extract.................................................10
	<8> CMD=>BAS................................................11
	<9> Dos Command.............................................12
	<0> Exit to Dos.............................................12

Appendix
	Object File Format..........................................13

                               +MACPAK DISK FORMAT+

The MacPak distribution disk is recorded in Model I single density format. It is directly readable by most operating systems as a data disk. The disk does not contain an operating system.

There is one file on the distribution disk which you should copy to your DOS disk. It is named:

			MACPAK/CMD

The Model III TRSDOS "CONVERT" utility can be used to copy the file to a system disk on that machine. MacPak can run on the Model 4 provided the machine is operating in the Model III mode.


+DISK OPERATING SYSTEM COMPATABILITY+

To process disk input/output MacPak uses the standard call addresses documented by Tandy, so most operating system will not require any patches to handle the program. The following DOS systems are known to operate successfully without modification.

	TRSDOS 2.3	(I)
	NEWDOS+		(I)
	NEWDOS80 V2	(I/III)
	LDOS 5.1.3	(I/III)
	DOSPLUS 3.4 & 3.5 (I/III)

Other operating systems will PROBABLY execute the MacPak functions without difficulty. The Dos Command option of MacPak may not work with alien systems.

Model III TRSDOS has a bug in the DIR command which can be corrected by the following patch. If operating under TRSDOS 1.3 instalation of this patch is recommended.

	PATCH *6 (ADD=5A65,FIND=32,CHG=3A)

This repairs a bug in the system which screws up the video display when a directory is taken without exiting through the command processor (as occurs when executing DIR from inside MacPak). This patch will have no negative effect on other applications, so can be applied to all your disks without causing any harm.


+MACPAK DEVELOPMENT+

MacPak was written by Lou Witt, and compiled using WIBASIC (Lou Witt Integer Basic). WIBASIC is available from Lou Witt, or from selected dealers.

+EXECUTION INSTRUCTIONS+

MacPak is a machine language program. To execute MacPak type the word MACPAK from the DOS READY mode.

+GENERAL INFORMATION+

+BACKUPS+:	Never use ANY editing utility, including MacPak, on a disk which doesn't have a safe backup. Disks may only be removed from the drives when the MacPak main menu is on the screen. At any other time, disk swapping could crash your files.

+FILESPECS+:	All "Filespec:" prompts will assume the "/CMD" extension if none is specified.

+BREAK+:		You may terminate any MacPak sub-function by pressing 8BREAK9.


+FUNCTION DESCRIPTIONS+

MacPak is a utility program designed to manipulate object format (machine language /CMD or /CIM) disk files. Each of the major functions is described briefly below.

+ZAP+:		Allows display and modification of bytes within a file using ascii or hexadecimal data.

+PATCH+:		Extends an object file with new or corrective machine code.

+MOVE+:		Redefines the load address of an object file. Will optionally generate a mover routine to move the data back to its original location after loading.

+MERGE+:		Allows 2 or more object files to be combined to form a single object file.

+MAP+:		Generates a listing of each object file load address segment and its corresponding disk location.

+LIST+:		Produces a dump listing of an object file including format marks delineating object, comment, and transfer segments.

+EXTRACT+:	Allows the extraction of any number of internal segments from any number of input files to form a single output file.

+CMD=>BAS+:	Creates a BASIC program which will poke a memory image of the contents of an object file when executed.

+MENU COMMANDS+

The main program loop is MacPak is through a menu screen. To select a function strike the appropriate number key. It isn't necessary to press 8ENTER9.

All MacPak functions except Exit will eventually return to the menu. Exit will return to the DOS READY mode.




+<1> ZAP+

The Zap function will prompt "Target Filespec:". Answer with the name of the file you wish to modify.

It will then display the current sector number and prompt "Sector?". Answer with the decimal number of the sector you wish to zap. MacPak will then display the contents of the disk sector.


+ZAP SCREEN+. The zap screen shows the current file name on the far left, the hex or ascii data in the center, and the display mode, relative sector, and last sector numbers on the far right.


+PAGING MODE+. When the sector contents are on the screen the following keystroke commands are recognized:

	;	Advance to next sector.
	+	Advance to last (highest) sector.
	-	Retard to previous sector.
	=	Retard to sector zero.
	X	Return to main menu.
	8BREAK9	Return to main menu.
	G	Issue "Sector?" prompt.
	A	Display using ASCII.
	H	Display using HEX.


The HEX mode displays all byte values in hex. The ASCII mode displays the ASCII (character) equivalent for the data bytes if they can be displayed. Any character which can't be displayed as ASCII is displayed as HEX.

When displaying the last sector in the file any bytes past the end of the file will display as "--". These bytes may be zapped by placing the cursor on the -first- "--" on the screen while in the modify mode and typing modification characters.


+MODIFY MODE+. When in the modify mode a flashing cursor will cover the byte being modified. Bytes are modified according to their display mode. The following keys are recognized in the modify mode:

	Arrows	Move the cursor up, down, left, or right. Shift arrows move
		the cursor to the extreme limits.

	8ENTER9	Write changes to file and return to paging mode.

	8CLEAR9	Cancel changes and return to paging mode.

	8BREAK9	Cancel changes and return to main menu.

If in the HEX mode the 0..9 and A..F keys will modify the cursor byte. In the ASCII mode A..Z,0..9, and the punctuation keys will modify the cursor byte.



+<2> PATCH+

The Patch function will prompt "Object Filespec:". Answer with the name of the file you wish to patch. MacPak will verify the file and display the transfer address.

+PATCH PROMPT+. The prompt "PATCH:" is answered with the address of the patch data in hex, followed by the hex data bytes separated by commas and terminated by 8ENTER9. When all patches have been entered answer the prompt with 8ENTER9.

	PATCH: 705E,C3,2D,408ENTER9
	PATCH: 8F21,AF,3E,FF,00,00,008ENTER9
	PATCH: 8ENTER9

After all patches have been applied MacPak will prompt "Xfer?". Answer with the transfer address in hex, or with 8ENTER9 if the transfer address is to be unchanged.



+<3> MOVE+

The Move function will prompt "Object Filespec:". Answer with the name of the file that is to be altered.

MacPak will then prompt "Low Memory Relocation Limit?". Answer with the minimum hex address of any object segment to be relocated. Code segments which load directly to video memory (below X'4000') or intended to modify the operating system (below X'5200') would be intentionally exempted from relocation. If no entry is given X'4000' is assumed.

The file will be scanned for origin, ending, and transfer addresses. The number of segments which load below the low memory limit will also be computed.

These will be displayed along with a "New Origin?" prompt. Answer with the hex address where you wish the code to load. The address values will be updated and redisplayed. When you are satisfied with the result answer the prompt with 8ENTER9.

The system will then prompt "Add Mover Routine?". If you wish MacPak to generate a machine code extension to the relocated file to move it back to its original location after loading from disk press "Y". It will then prompt "Disable Interrupts?". If the code is being moved into a section of memory which may interfere with the interrupt service routines key "Y".

The transfer address will be displayed and the prompt "Xfer?" issued. If the transfer address is satisfactory key 8ENTER9, otherwise type the appropriate hex address.

MacPak will then re-scan the file updating the address markers and (if specified) add the mover routine.



+<4> MERGE+

The Merge function will prompt "Output Filespec:". Answer with the name of the file which will contain the combined object files.

MacPak will then ask "Input Filespec:". Answer with the name of the object file to be merged. It will be verified and transfered to the output file. The transfer address of the input file will be displayed on completion of the file copy.

When all the input files have been merged answer the "Input Filespec:" with 8ENTER9 to signify that all input files have been processed.

Merge will then prompt "Xfer Address:". Answer with the hex address to be used as the file transfer address. If no entry is given the transfer address from the last file loaded will be used.

NOTE: When merged files contain overlapping address segments the data in the -latter- file takes precedence. This allows machine language modifications to existing programs to be assembled, then merged with existing object files to effect extensive patches.


+<5> MAP+

The Map function will prompt "Target Filespec:". Answer with the name of the object file you wish to map.

It will then prompt "Object Address Range?". Answer this prompt with the hexadecimal range of load addresses you wish mapped. If you answer the prompt with "5700,89008ENTER9" only those object segments which load data within the range X'5700' thru X'8900' will be mapped.

Answering "Object Address Range?" with 8ENTER9 will map the entire file.

Map will then prompt "Hardcopy?". Press "Y" to route the map to the line printer.

One line for each load segment in the file will be displayed/printed. A typical line is:

	*'8E00'-'8EFD' <254> Sec=  0 Byte@ 04 Abs=     4 (     0,  257)

The meaning of each of the map line elements is as follows:

+*+		Indicates this object segment does not load immediatly after
		the preceeding object segment.
+'8000'-'8EFD'+	This is the hex load range of the object segment.
+<254>+		Decimal number of bytes in the load segment.
+Sec=  0+		Decimal sector number.
+Byte@ 04+	Hex offset of byte where object segment data field begins.
+Abs=   4+	Absolute decimal offset from start of file to start of object
		segment data field.
+(   0, 257)+	Absolute decimal range of object segment, -including- format 
		characters (can be used by Extract function).

The final line of the map display will be the transfer record which follows the same general format, as in the following:

	Xfer=>'5200' <  2> Sec=  1 Byte@ B4 Abs=  436 (  434,  437)


+<6> LIST+

The List function will prompt "Target Filespec:". Answer with the name of the object file you wish to list.

The "Sector Range?" prompt will then be issued. Answer with the decimal range of sector numbers you wish to list. If you answer the prompt with "3,108ENTER9" only sectors 3 through ten will be listed.

Answering "Sector Range?" with 8ENTER9 will list the entire file.

List will then prompt "Hardcopy?". Press "Y" to route the list to the line printer.

The data from the file is displayed in groups of 16 bytes. Hex and ascii values are displayed.

There are three typse of segments in an object file (see Appendix for file formats). In the listing the format control byte will be prefixed with ".", load segments are indicated by "L", comment segments by "$" and the transfer segment by "!". Typical examples follow.

+OBJECT SEGMENT+
0/00 .01L12 00/40 00 01 02 03  04 05 06 07 08 09 0A 0B  !...

                                                ASCII dump
                                      HEX dump
                Load address of data in LSB/MSB format
           Segment length
          "L" indicates load segment
       "." indicates format byte
     Hex byte offset of first byte of line
   Decimal sector number

+COMMENT SEGMENT+
0/30 .05$06 42 41 53 49 43 42 .01 EB 00/40 C3 46 53 C3  !..BAS

                                Beginning of next segment
                      Comment data (usually ASCII)
            Length of segment
           "$" indicates a comment segment

+TRANSFER SEGMENT+
9/67  8A 66 DE.02!02 AD/5B --  -----------------------  !...

                             Bytes following transfer are null
                         Hex transfer address in LSB/MSB format
                   "!" indicates transfer segment
           Trailing bytes of previous segment



+<7> EXTRACT+

The Extract function will prompt "Output Filespec:". Answer with the name of the file to receive the extracted data.

Extract will then prompt "Source Filespec:". Answer with the name of the file containing the data to be extracted.

Extract will then prompt "File Address Range?". There are two acceptable formats for specifying the file address range.

If you type two values Extract will assume they are absolute byte addresses. Answering "0,9" would extract ten bytes starting at the first and ending at the tenth.

If you type four values Extract will assume the are sector/byte pairs. Answering "2,0,3,255" would extract bytes starting in sector number two at byte zero and ending at sector 3 byte 255.

After the "File Address Range?" is specified the bytes will be copied from the source file to the output file and the "File Address Range?" will be issued again.

When all the desired segments from the source file have been extracted answer the address range prompt with 8ENTER9 to return to the "Source Filespec:" prompt.

When all source files have been processed answer the prompt with 8ENTER9.

Extract will then prompt "Xfer Address:". Type the hex address for the transfer segment. If no address is entered the transfer segment will not be applied.



+<8> CMD=>BAS+

This function will prompt "Output (/BAS) filespec:". Answer with the file name to receive the generated BASIC program.

It will than ask "Initial Line#?". Answer with a number higher than any used in the existing BASIC program. A typical value would be 60000.

Answer the "Line # Increment?" with the increment value to be used as basic lines are generated.

Answer the "GOTO Line # For Exit?" with the line number where execution is to commence after the machine code has been poked to memory.

Answer the "Memsize Reset Address?" with the hex value to be used as the MEMSIZE value -or- with the decimal value suffixed by "T". If no value is entered the MEMSIZE won't be altered.

The system will then ask "Input (/CMD) Filespec:". Answer with the object code file to be converted.

MacPak will display the hex addresses of the load blocks as the object file is translated, followed by the transfer address.

The system will then repeat the "Input (/CMD) Filespec:". If another file is to be included answer as specified above. Otherwise press 8ENTER9.

+EXAMPLE USE.+ Assume the normal execution procedure for a particular program was to "LOAD USR1/CMD" from DOS READY mode, then enter BASIC and answer MEMSIZE? with 42000 then RUN "GAME1/BAS". To abbreviate this the USR1/CMD program and the MEMSIZE? reset function can be incorporated in the GAME1/BAS program.

Generating the /BAS image of USR1 would be done using CMD=>BAS as follows:

	Output (/BAS) filespec: USR1/MRG8ENTER9
	Initial Line #? 650008ENTER9
	Line # Increment? 18ENTER9
	GOTO Line # For Exit? 28ENTER9
	Memsize Reset Address? 42000T8ENTER9
	Input (/CMD) Filespec: USR1/CMD8ENTER9
	.
	.	8 displays load segments 9
	.
	Input (/CMD) Filespec:8ENTER9

The USR1/MRG file would contain the data in the USR1/CMD file along with a BASIC program to poke it to memory.

Merging the USR1/MRG file would be done using BASIC. The GAME1/BAS file would be loaded then USR1/MRG merged. The following lines would be added:

	1 GOTO 65000 'reset memsize and poke usr routines
	2 ' re-entry from usr routine poking

The new GAME1/BAS file could then be saved to disk.



+<9> DOS COMMAND+

This function will display the words "Dos Ready", then wait for input. If nothing is entered control is returned to the MacPak menu. Any other entry is passed to the DOS for execution. No function should be executed which would interfere with memory between X'7000' and X'BFFF'.



+<0> Exit to Dos+

This function will exit MacPak and return control to your disk operating system.


+APPENDIX --- OBJECT FILE FORMAT+

Object files are stored on disk as sequential files consisting of three types of segments: 1) Object 2)Comment 3)Transfer.

Regardless of the segment type, the format is identical. The first byte is a segment code which tells the loader what type of segment it is. The second byte is the length specifier. The remaining bytes are the segment data.

Explanations of each segment type follow:

<01>	OBJECT RECORD
This is where the action is. Code 1 is the the segment header code to indicate the loader is to copy from the file to the computer memory.

	<01>	Object header
	<nn>	Length of loader field+2
	<lsb>	Least signifigant byte of load address
	<msb>	Most signifigant byte of load address
	<d....>	Data to load to memory

<02>	TRANSFER RECORD
This is the final segment in every object file. It tells the loader where to transfer microprocessor control.

	<02>	Transfer header
	<02>	Usually 2, but any value will work
	<lsb>	Least signifigant byte of transfer address
	<msb>	Most signifigant byte of transfer address

<05>	COMMENT RECORD	(also 00,01,03,04,06..1F)
This segment type is used to embed exteraneous information inside object files (such as copyright messages). Some of the advanced operating systems and assemblers generate special information in comment records. Using Map in conjunction with Zap will usually reveal any special cases your DOS may have.

	<05>	Comment header
	<nn>	Number of characters in comment
	<c...>	Comment data


Any header value greater than '1F' is invalid and will produce an error when loaded or executed.

+NOTES+


+NOTES+


MacPak is a machine language file editing utility designed for the manipulation of object (/CMD type) files. Menu driven operation along with extensive error trapping allows easy operation by users of all skill levels. Whether you're zapping your disk operating system or just want to learn how object files work, MacPak is for you!


+MACPAK FUNCTION DESCRIPTIONS+


+ZAP+: Allows display and modification of bytes within a file using ascii or hexadecimal data.

+PATCH+: Extends an object file with new or corrective machine code.

+MOVE+: Redefines the load address of an object file. Will optionally generate a mover routine to move the data back to its original location after loading.

+MERGE+: Allows 2 or more object files to be combined to form a single object file.

+MAP+: Generates a listing of each object file load address segment and its corresponding disk location.

+LIST+: Produces a dump listing of an object file including format marks delineating object, comment, and transfer segments.

+EXTRACT+: Allows the extraction of any number of internal segments from any number of input files to form a single output file.

+CMD=>BAS+: Creates a BASIC program which will poke a memory image of the contents of an object file when executed.



MACPAK (Object File Editing Utility) V.2.1 (c) 1983  by Lou Witt
 Lou Witt - P.O.Box 2135 - Sanford, FL 32772 <voice: 305/322-4675>

   .......... M E N U ..........

	<1> Zap			<2> Patch
	<3> Move		<4> Merge
	<5> Map			<6> List
	<7> Extract		<8> CMD=>BAS
	<9> Dos Command		<0> Exit to Dos

		Your Selection (0-9)?
 