README file for ap2inf v1.4.2 ----------------------------- This program was written to extract the data from Apl2em disk images of Infocom adventure games and and store it in the standard Infocom data file format so that it can be played with other interpreters on other systems. Of course, if in doing so you contravene the game's copyright agreement then you shouldn't do so. Also, if using this program directly or indirectly causes your house to burn down, your collection of digitised pictures of questionable moral value to be deleted, your goldfish to die, or anything else to happen then it is your fault and not mine. Just to set your mind at rest... none of the above have ever, as far as I know, happened as a result of using ap2inf. :) Contents of archive ------------------- Included in this archive should be: README (this file) ap2inf.c (the ANSI C source) ap2inf.exe (MSDOS executable because a lot of people who have MSDOS or Windows don't have a C compiler) Disk images ----------- In order to extract the data file from a disk image, you first need a disk image. Disk images are binary dumps of all the data on a disk into a file. These are typically used with emulators, so that disks from the emulatED machine can be read as files on the emulatING machine. How to use ap2inf ----------------- A number of features have appeared in version 1.4 that were not in version 1.3. All of these are available by use of command-line options, so I'll just give an explanation of the options. The interactive bits that were in version 1.3 have disappeared. To use ap2inf your command line should look something like this: ap2inf [options] is the name of an Apl2em-compatible disk image file in the current directory and is the name of the data file that the program will create. If a file of this name exists, it will be overwritten, so be careful. and are required, whereas [options] are... optional. The options can be one or more of the following: -h This gives help in using ap2inf. Since you're reading this file you probably shouldn't need to use this option. The program will not extract anything if this option is found. -ix This is to specify the sector interleaving scheme to use. Using -i0 will cause the program to assume that the disk has no interleaving, which is true for most games. Using -i1 assumes standard DOS 3.3 interleaving such as interpreter E uses. -lxxx This option allows the user to specify the length of the data file to extract. With most games this information is stored in the game header, but with the older games it is not. If there is no data length in the game header and none is specified on the command line then the maximum possible length of 131072 bytes is used so as to be sure not to truncate the data. -cxxx This option allows the user to specify the checksum to use to check the integrity of the data file. As with the data length, this is usually stored in the game header but is absent in the older games. -pxxx This is to specify padding. Older interpreters used to a use virtual memory style paging scheme due to memory constraints. Thus data files were padded with zeros to fill up the last page to the page size the interpreter used. Common values are 256 or 512 bytes. I'm sure that none of the modern commonly-used interpreters need the files to be padded in this way. Notice that there is no space between the letter indicating the option and the number that follows it. Numbers can be either decimal or hexadecimal (or octal too, I suppose). Hexadecimal numbers must begin with "0x", ie 33 decimal = 0x21 hex. Comments on data lengths and checksums -------------------------------------- Comments about data lengths and checksums... Specifying a data length longer than that of the actual data should not affect the correctness of the data file, since the interpreter won't read past the end of where it needs to and the checksum should still be correct because the extra bytes are all zero. If you have a disk image of an old game (old versions of Zork I, Zork II and Deadline) then you can either go with making up your own length or you can use the lengths (and checksums) that are in the Infocom Fact Sheet that Paul David Doherty maintains. (You can fine it on ftp.gmd.de in /if-archive/infocom/docs/fact-sheet.txt.) Some of the disk images of old games that I've come across have a bit of the third last track repeated after the end of the data, making up the rest of the partial last track. Because of this, extracting a data file longer than the end of the actual data will cause the checksum to fail, even though all the valid data is actually intact. Games that ap2inf works on -------------------------- Ap2inf 1.4.1 has been tested on games running under interpreters B, E, H, K and M. Earlier versions of ap2inf used to stop if they did not recognise the interpreter, but now it just uses a default de-interleaving scheme in such cases (which you can change with -i if it doesn't work). If anyone has any images of games with other interpreters, I'd appreciate it if you could send them to me so that I could get ap2inf to recognise them. Some games have messages from hackers stuck onto the front of them, which confuses ap2inf since it won't find the signature bytes for which it searches. These will then have to be treated as a different case. Of course, it's just detecting the interpreter that won't work and you can run ap2inf on it anyway, specifying the interleave pattern if it doesn't work the first time. Systems that ap2inf works on ---------------------------- The program is written in ANSI C and the source is provided, so it should (at least theoretically) be portable to any system that has an ANSI-compliant C compiler. I've compiled and run it without any problems on the following systems: Systems running Unix SysVR4 Sun machines running SunOS 5.4 SGI machines running IRIX 5.3 DEC Alpha AXP running OpenVMS V6.2 PC's running Linux PC's running MSDOS or Windows 95 with Turbo C++ v3.0 and Borland C++ v4.5 The compiler that I used under SunOS 4.1 was nasty (and old) and wanted me to put my definitions for the parameters under the function header in the old way but I didn't feel like doing that, so I didn't. If anyone finds any errors in ap2inf or has any suggestions or comments or whatever, I'd be glad to hear them. Stephen Tjasink stjasink@cs.uct.ac.za