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 ----//----