	Program usage documentation for ARK

	(c) Copyright 1998 by K. Heidenstrom.

	Modified:

	KH.19980815.001  First version, for ARK 1.0.0
	KH.19980823.002  Added system requirements

1.  LEGAL

	The ARK package, including the source and executable files and this
	documentation, are (c) Copyright 1998 by K. Heidenstrom.  The author
	can be reached at kheidens@clear.net.nz or by snail mail:
	K. Heidenstrom c/- P.O. Box 27-103, Wellington, New Zealand.

	This program is free software.	You may redistribute the source and
	executable(s) and/or modify the program under the terms of the GNU
	General Public License as published by the Free Software Foundation;
	either version 2 of the License, or (at your option) any later version.

	This program is distributed in the hope that it will be useful, but
	is provided "as-is", without any warranty of any kind, including
	the implied warranty of merchantability or fitness for a particular
	purpose.  In no event will the author be liable for any damages of
	any kind related to the use of this program.  See the GNU General
	Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

2.  FUNCTION

	ARK is a program archiver and executer stub for MS-DOS.  It allows you
	to create executable files which contain one or more smaller programs,
	and to execute the programs directly from the archive, without the need
	to extract them to disk.  ARK is useful for combining large numbers of
	small utility programs into a single file, to save disk space and make
	collections of small programs easier to manage.  The resulting file can
	then be compressed by an executable file compressor like PKLITE, LZEXE,
	DIET etc, to save even more space.

	ARK stores COM-type programs.  It cannot store EXE programs directly.
	For MS-DOS-only EXE programs that are smaller than about 64K, you may
	be able to use the accompanying EXC program to convert the EXE file to
	a COM file so it can be incorporated into an ARK archive.  See the
	documentation (EXC.TXT) for details.

	ARK cannot store Windows or OS/2 executables.

	ARK is similar to a utility called XEQ, which was written by Colin J.
	Stearman (71036.256@compuserve.com) in 1987 and maintained until 1993,
	but there are several differences.  In general, the ARK stub is smaller
	and much simpler than XEQ's stub, and because ARK is an EXE file, the
	ARK archive total size is not limited to 64K as it is with XEQ.

	ARK is not related to ARC files, an old type of compressed file archive
	maintained by programs like ARCE, PKXARC, PKPAK and PKUNPAK.

3.  OPERATION

	An ARK file consists of two parts - the ARK stub (ARK.EXE in this
	package) and zero or more archived programs.  The ARK stub has the
	ability to run an archived program directly from the archive, and to
	perform some basic archive maintenance functions.  Whenever the archive
	changes, the ARK stub recreates the image of the ARK file on disk, to
	include the ARK stub and the updated archive contents.

	The ARK.EXE file in this package is the ARK stub, with no programs in
	its archive.  The ARK stub allows you to update the archive which is
	attached to the stub, so you can add programs to the stub to make a
	useful ARK file.

	Because every ARK file contains the ARK stub, and the ARK stub includes
	the basic archive maintenance functions, you can clone ARK and make as
	many ARK archives as you like.	Just take an existing ARK file and copy
	it to a new name.  You can then make a temporary directory, put some
	COM-type programs in it, and run the newly copied ARK program to rebuild
	itself using those programs.

	For example, you can create an ARK file for each type of utility you
	have, such as file maintenance, TSRs, diagnostics, etc, and put the
	appropriate programs into each ARK file.  You could name the ARK files
	appropriately (e.g. FILE.EXE, TSRS.EXE, DIAG.EXE).  Because the size
	of an ARK file is limited only by available memory, you may be able to
	put all your COM-type utilities into a single ARK file.

	ARK does not support Windows 95/98/NT-style long filenames.

4.  USAGE

	ARK provides four functions.  Running ARK with no parameters displays
	the usage summary:

		ARK Command [Parameters]	- Run specified command
		ARK -E Filespec 		- Extract file(s) to disk
		ARK -L				- List archive
		ARK -R				- Rebuild archive from *.COM

4.1  RUN COMMAND DIRECTLY FROM ARCHIVE

	The first line shows how to run a program directly from the ARK file.
	For example if the ARK file includes the program DUMPPSP.COM, you can
	run it directly from the archive by typing ARK DUMPPSP followed by any
	parameters to be passed to DUMPPSP.  For most programs, this is similar
	to running the original program directly from the command line, except
	of course that the program exists only inside the ARK file.

	There are some differences between running a command from an ARK file
	and running it directly from disk.  See section 6 for details.

	The next three lines show ARK's archive maintenance functions.  The
	switch may begin with a hyphen ('-') as shown, or with the current DOS
	switch character, which is normally a forward-slash ('/').

4.2  EXTRACT FILE(S) FROM ARCHIVE

	The second line shows how to extract one or more files from the ARK
	file.  The archive is not modified when files are extracted.  Any files
	which already exist will be overwritten by files of the same name in
	the archive.  There is no prompt to ask you whether to overwrite an
	existing file of the same name.

	You must give a file mask, called 'Filespec' above, to specify which
	file(s) are to be extracted.  This filespec may contain wildcards but
	must not contain a path specification (drive and/or directory) and
	it must not contain an extension.  For example, ARK -E DUMPPSP and
	ARK -E * are acceptable but ARK -E C:\DUMPPSP and ARK -E DUMPPSP.COM
	are not.  An inappropriate name will cause ARK to either display the
	usage message, or to extract no files.

	The file(s) are extracted to the current default directory, and their
	original date, time and size are restored.  If you want to extract
	files to a directory which is different from the directory where the
	ARK file is located, change to the target directory and run the ARK
	file explicitly from the directory where it is located.  For example
	to extract an ARK file called C:\UTIL\UTILS.EXE to directory C:\TEMP,
	you would use the following commands:

		CD \TEMP
		\UTIL\UTILS -E *

	A dot is displayed for each file that is extracted.  If you don't want
	progress indications, reassemble the stub with SHOW_PROGRESS set to 0.

	If you specify a file which is not in the archive, ARK will simply not
	extract any files.  It does not display an error message.  You can tell
	that no files have been extracted because no progress indicator dots
	are displayed.

	If an error occurs during file extraction, ARK issues an error message
	and terminates.  The most likely reasons for an error are:

		Running out of disk space during the extraction.  In this case,
		the file which would not fit will appear to be present on the
		disk but it will only contain part of the file contents.  After
		making room for the extracted files, re-extract the archive so
		the partial file is replaced with a correct, complete file.

		Trying to extract on top of a file which already exists and is
		is read-only.  In this case, use ATTRIB or a similar program
		to remove the read-only attribute on any files that will be
		replaced by the extraction process, and try again.

4.3  LIST ARCHIVE

	The -L command causes ARK to list the contents of the archive.	This is
	done fairly tersely.  Each file is listed on a separate line, like a
	directory listing.  An example line would be:

		DUMPPSP  COM  1174  19921120  01:02

	This line indicates that the filename is DUMPPSP.COM (the extension is
	always 'COM'), its size is 1174 bytes, its date is 20 November 1992 and
	its time is 01:02 a.m.

4.4  REBUILD ARCHIVE FROM ALL COM FILES IN CURRENT DIRECTORY

	The -R command instructs ARK to rebuild its archive from scratch.  The
	previous contents of the archive is lost, and the archive is rebuilt,
	using all COM files in the current directory, in the order in which
	they appear in the directory.  The rebuild works by loading the program
	files into memory, then recreating the ARK file's image on disk.

	To update an existing ARK archive, extract all files to disk using the
	ARK -E * command, use DOS commands or file maintenance utilities to
	update the files on disk (e.g. replace an old version of a program with
	a newer version, add a new program, delete unwanted programs, etc),
	then rebuild the archive using the ARK -R command.

	You can include any file except an EXE file in an ARK archive, as long
	as you rename it to have a COM extension.  If the file is internally an
	EXE file (if it has an EXE header beginning with the characters 'MZ'),
	ARK will report an error and abort, but other files such as text files
	can be included in an ARK archive if they are given a COM extension.
	This could be useful for including documentation in the archive, so it
	can be extracted later, but do not use the execute function with a
	file which is not an executable program, and be sure to rename it to
	a sensible extension after extracting it, because trying to execute a
	text file as a program will probably crash the machine!

	A dot is displayed for each file that is read into memory, and a star
	(asterisk) is displayed for every 64K block (approximately) that is
	written to disk when the ARK file's image on disk is recreated.  If you
	don't want progress indications, reassemble the stub with SHOW_PROGRESS
	set to 0.

	If an error occurs during the archive rebuild operation, ARK issues an
	error message and terminates.  The most likely causes of errors are:

		Running out of memory during the rebuild.  ARK requires enough
		memory for the stub, the files being put into the archive, and
		2 kilobytes for its stack.  If there is insufficient memory
		available, ARK aborts without modifying its image on disk.

		Attempting to include an EXE file.  Sometimes an EXE file is
		renamed to a COM file, but is still an EXE file, because it has
		an EXE header, which starts with the signature letters 'MZ'.
		For example, DOS's COMMAND.COM has been an EXE file in disguise
		since about DOS version 4.0.  If you try to add a file which
		starts with 'MZ', ARK aborts without modifying its disk image.
		ARK also checks the COM file length.  If it contains zero
		bytes, or is larger than 65274 bytes, ARK will report an error.

		Running out of disk space when the rebuilt archive is being
		written to disk.  This would happen if the archive grows and
		there is not enough room to hold the new ARK file.  In this
		case, ARK deletes the partial archive data from the file, so
		the image on disk then contains no archived programs, but the
		ARK stub is preserved, so you can free up some disk space and
		try the archive rebuild operation again.

		Trying to update an ARK file which is read-only.  Remove the
		read-only attribute from the ARK file using ATTRIB or a similar
		utility, and run the rebuild again.

5.  GENERAL NOTES

	ARK does not compress files.  ARK files can be compressed by executable
	file compressors such as PKLITE or LZEXE.  However, when the archive is
	rebuilt (the ARK -R command), an uncompressed version is written to
	disk, and the compressor must be run again to re-compress the ARK file.

	Even without compression, ARK saves disk space because it avoids the
	waste caused by DOS cluster allocation.  For example, a 1GB hard drive
	using the DOS FAT-16 file system allocates space in clusters of 16
	kilobytes each.  If you have ten 2-kilobyte files, each file requires
	one cluster, so instead of occupying 20480 bytes, they occupy 163840
	bytes.	As an ARK archive they would occupy 32768 bytes (two clusters).
	If you have gigabytes of hard disk storage, you probably won't care
	about wasting a few hundred kilobytes, or even a few megabytes, but on
	floppy disks (e.g. emergency disks) the space saving can be significant.
	Also, you may find that having all your small utility programs combined
	into a single file (or a few files) makes them easier to deal with.

	The size of an ARK file is the stub size (the size of the initial
	ARK.EXE file in this package) plus space occupied by the files.  For
	each file, the space occupied is equal to the file size rounded up if
	necessary to a multiple of 16, plus 16.  For example, a file with a
	length from 1 to 15 bytes will occupy 32 bytes; a length of 16 to 31
	will occupy 48 bytes; a length of 32 to 47 will occupy 64 bytes, etc.

	I find it convenient to have a single ARK file, containing all my small
	utilities, but there are two reasons why you might want to keep the ARK
	file sizes small, and possibly use several smaller ARK files rather
	than one larger one.  First, load time from floppy disk (if the ARK is
	to be used on an emergency disk, etc).	If a disk cache is present,
	this is less of a problem.  Secondly, memory requirement.  ARK requires
	enough memory to hold the entire executable file, plus two kilobytes.
	If the ARK file is compressed by PKLITE, LZEXE etc, this will disguise
	the true amount of memory required for the file, and the decompressor
	code will also slightly increase the amount of memory required.  If you
	may need to run the ARK on low memory systems you should consider this.

6.  INTERNAL DETAILS

	This section describes the differences between running a program
	directly from the command line, and running it from within an ARK
	archive.

	DOS informs a program of the full path and file name of its image on
	disk, via a string which is tacked onto the end of the environment.
	Some programs make use of this string, usually so that they can modify
	their image on disk (for example, if they have default options which
	can be changed, like Borland's Turbo GREP), or so they can display
	their own true name in messages to the user.

	Because a program executed directly from an ARK archive does not exist
	on disk, and therefore does not have a meaningful path and file name,
	I have chosen not to try to provide a valid path and file name.  The
	ARK stub simply replaces the path and file name string with 'NUL'.
	This may cause problems with some programs.  Some programs may report
	their own name as 'NUL' in messages.

	To update the settings in a program which contains default settings in
	its executable, you must extract the archive to a temporary directory,
	run the program directly and allow it to update the settings in its
	image on disk, then rebuild the archive, so that the updated executable
	is placed into the ARK archive.  For example:

		MD TEMP			Create a temporary directory
		CD TEMP			Change into it
		..\ARK -E *		Extract all files into temp directory
		GREP -i -u		Update options in GREP.COM
		..\ARK -R		Rebuild archive
		CD ..			Change back to starting directory
		DEL TEMP\*.COM		Delete files in temporary directory
		RD TEMP			Remove temporary directory

	There are two other differences between direct execution and execution
	via ARK, which relate to the default FCBs and the value in the AX
	register at the start of execution.  I doubt that either of these will
	be a problem, except maybe with very old programs (early 1980s).  Under
	ARK, the names in the FCBs are the names provided by DOS when ARK was
	executed, so the first default FCB name will be the name of the program
	being executed, not the first filename passed to it, and the second
	default FCB will contain the first parameter passed to the program
	being executed.  Under ARK, the AX register on entry to the program is
	always zero.

7.  COMPARISON WITH XEQ

	I have not disassembled XEQ to determine exactly how it works.	Working
	from the documentation for XEQ version 1.60 (which seems to be the
	latest version of XEQ) I have made a list of differences between ARK
	and XEQ.

	The major differences are (a) the ARK stub is smaller and simpler than
	the XEQ stub and provides cruder archive maintenance functions, and
	(b) the ARK archive size is not limited to 64K, because ARK is an EXE
	file.  (XEQ is a COM file so it cannot be larger than 64K in size.)

	ARK's archive maintenance functions are crude compared to XEQ.  ARK
	supports only four functions:

		Execute command directly from archive,
		List the archive contents,
		Extract one or more files to the current directory,
		Rebuild whole archive from all COM files in current directory.

	I did this because from my own experience using XEQ, I found that the
	best way to maintain an XEQ archive was to extract all files to disk,
	use file maintenance programs to work with the files on disk, then
	rebuild the archive from scratch.  With ARK, you must use this method.

	ARK is much less verbose than XEQ.  ARK has only six error messages,
	and only displays a message if there is an error.  ARK does not show
	totals, calculate bytes saved etc.  I did this because I like terse
	programs, and because it keeps the stub small.

	ARK executes commands from within the archive only.  If the command is
	not present in the archive, ARK gives an error message and terminates.
	With XEQ, if the command is not in the archive, the XEQ stub invokes
	the command processor, to execute the command externally.  I made a
	deliberate choice here; I prefer the simpler, less ambiguous behaviour.

	XEQ has some special features (the AUTOXEQ.COM file, some command line
	switches) which are not duplicated by ARK.

	ARK requires MS-DOS version 3.0 or later.  XEQ still supports DOS 2.x
	though its behaviour differs slightly under DOS 2.x because DOS 2.x
	does not provide the pathname to the executable in the environment
	block.	I don't know anyone who still uses DOS 2.x so I don't feel any
	need to support it.  It wouldn't be difficult to add crude DOS 2.x
	support, though.

8.  SYSTEM REQUIREMENTS

	CPU:		8086 or later
	Memory:		As much system memory as possible
			(archive size is limited by available memory)
	OS:		DOS 3.0 or later, or Windows 3.x/95/98/NT or OS/2

				   ----//----
